# WhatsApp Templates API

WhatsApp-Nachrichtenvorlagen sind vorformulierte Nachrichten, die für den Versand außerhalb des normalen 24-Stunden-Konversationsfensters genehmigt wurden – zum Beispiel eine Willkommensnachricht, eine Terminerinnerung oder ein Impuls zur erneuten Interaktion. Diese API ermöglicht es Ihnen, Vorlagen programmgesteuert aufzulisten, zu erstellen, zu bearbeiten, einzureichen, zu überprüfen, zu löschen und zu versenden.

Alle unten aufgeführten Pfade sind relativ zur API-Basis-URL:

```
https://api.youraiconnector.com/v1
```

Jede Anfrage muss authentifiziert sein. Siehe [Authentifizierung](authentication.md) für die vier akzeptierten Methoden. Die Beispiele auf dieser Seite verwenden den `X-API-Key`-Header (und eine Abfrageparameter-Form für cURL).

::: note
**Hinweis:** Vorlagen basieren auf dem WhatsApp Business API-Kanal. Daher erfordert dieser Teil der API sowohl API-Zugriff als auch einen Plan, der WhatsApp-Kanäle beinhaltet. Ohne diese werden Anfragen mit einem `403` abgelehnt.
:::


---

## Arbeiten mit Unterkonten (Agenturen)


---

## Genehmigungsstatus

Da Nachrichten, die außerhalb einer offenen Konversation gesendet werden, zuerst von WhatsApp überprüft werden müssen, trägt jede Vorlage einen Genehmigungs-`status`:

| Status | Bedeutung |
|---|---|
| `draft` | Erstellt oder gespeichert, aber noch nicht zur Überprüfung eingereicht. Sie können sie noch bearbeiten. |
| `received` | Eingereicht und in die Überprüfungswarteschlange aufgenommen. |
| `pending` | In Überprüfung. |
| `approved` | Zum Versand freigegeben. |
| `rejected` | Abgelehnt. Das Feld `rejection_reason` erklärt den Grund; korrigieren Sie es und reichen Sie es dann erneut ein. |

Nur `draft`- und `rejected`-Vorlagen können bearbeitet oder (erneut) eingereicht werden. Sobald eine Vorlage `approved` ist, ist sie gesperrt – erstellen Sie eine neue, falls Sie Änderungen benötigen.

> **Automatische Genehmigung:** Einige Kanäle erfordern keinen externen Überprüfungsschritt. Vorlagen, die für eine Kampagne auf einem solchen Kanal erstellt oder eingereicht werden, werden sofort als `approved` gespeichert, ohne Inhalts-ID (`sid`).

---

## Vorlagen für Meta-verbundene Konten

Diese Endpunkte funktionieren auf die gleiche Weise, unabhängig davon, welche WhatsApp-Verbindung Ihr Konto verwendet, aber die Vorgänge im Hintergrund unterscheiden sich:

- Bei einer **verwalteten WhatsApp-Verbindung** werden Vorlagen beim Messaging-Anbieter registriert und `sid` ist die Inhalts-ID des Anbieters (`HXXXXXXXX…`).
- Bei einem Konto, dessen Nummer über ein **eigenes WhatsApp Business-Konto** läuft (beide Meta-Verbindungsoptionen), werden Vorlagen **in diesem WhatsApp Business-Konto** erstellt und geprüft, und `sid` ist die eigene Vorlagen-ID von Meta – eine numerische Zeichenfolge wie `"3394843740694756"`. `status` verwendet weiterhin die Werte in der obigen Tabelle, und `rejection_reason` enthält weiterhin die Erläuterung von Meta.

Dafür gibt es zwei zusätzliche Endpunkte: einen, um abzufragen, welche Verbindung Sie nutzen, und einen, um Ihre Vorlagenliste mit Ihrem WhatsApp Business-Konto abzugleichen. Vorlagen, die bereits im WhatsApp Business-Konto vorhanden sind, werden durch die Synchronisierung in Ihre Bibliothek importiert, sodass ein anschließender `GET /whatsapp-templates` sie wie jede andere Vorlage auflistet.

### Überprüfen, über welche Verbindung Vorlagen laufen

`GET /whatsapp-templates/provider`

| Feld | Beschreibung |
|---|---|
| `provider` | `twilio`, wenn Vorlagen beim verwalteten Messaging-Anbieter registriert sind, `meta`, wenn sie in Ihrem eigenen WhatsApp Business-Konto liegen. |
| `lane` | Welche Meta-Verbindung verwendet wird – `meta_cloud_api` (Ihre eigene Meta-App) oder `meta_embedded` (verbunden über unsere Meta-App). `null` bei einer verwalteten Verbindung. |
| `waba_id` | Das WhatsApp Business-Konto, in dem die Vorlagen erstellt werden, oder `null`. |
| `templates_enabled` | `false`, wenn die Meta-Verbindung noch nicht abgeschlossen ist (kein WhatsApp Business-Konto oder Zugriffstoken gespeichert). Das Erstellen oder Einreichen von Vorlagen schlägt bis dahin mit einem `400` fehl. |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/whatsapp-templates/provider?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/provider", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/provider",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Antwort**

```json
{
  "success": true,
  "provider": "meta",
  "lane": "meta_cloud_api",
  "waba_id": "2357661648036355",
  "templates_enabled": true
}
```

### Vorlagen von Meta synchronisieren

Aktualisiert den Genehmigungsstatus jeder Vorlage, die in Ihrem WhatsApp Business-Konto vorhanden ist, und importiert jede Vorlage, die dort existiert, aber noch nicht in Ihrer Bibliothek enthalten ist. Kann bedenkenlos so oft aufgerufen werden, wie Sie möchten. Bei einer verwalteten Verbindung gibt es nichts zu synchronisieren, daher bewirkt der Aufruf nichts und meldet lediglich, wie viele Vorlagen Sie haben.

`POST /whatsapp-templates/meta-sync`

| Feld | Beschreibung |
|---|---|
| `imported` | Vorlagen, die im WhatsApp Business-Konto gefunden und durch diesen Aufruf zu Ihrer Bibliothek hinzugefügt wurden. |
| `updated` | Bestehende Vorlagen, deren Status oder Details sich geändert haben. |
| `total` | Vorlagen in Ihrer Bibliothek nach der Synchronisierung. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Antwort**

```json
{
  "success": true,
  "provider": "meta",
  "imported": 2,
  "updated": 5,
  "total": 12
}
```

### Direkte Kommunikation mit Meta (fortgeschritten)

Wenn Sie etwas benötigen, das die oben genannten Endpunkte nicht bereitstellen – Vorlagen-Header, -Footer, -Buttons oder eine vollständig manuell erstellte Vorlage –, leitet `/v1/meta-templates` Ihre Anfrage direkt an die eigene Vorlagen-API von Meta weiter, ohne etwas in Ihrer Vorlagenbibliothek zu speichern. Dies funktioniert nur bei Konten, deren Nummer über ein eigenes WhatsApp Business-Konto läuft; bei einer verwalteten Verbindung gibt jeder Aufruf `400` zurück und fordert Sie auf, zuerst eine Meta-App zu verbinden.

| Endpunkt | Funktion |
|---|---|
| `GET /meta-templates` | Listet die Vorlagen in Ihrem WhatsApp Business-Konto mit ihrem aktuellen Status auf. Fügen Sie `?name=` hinzu, um nach einem exakten Vorlagennamen zu filtern. Gibt `{ "success": true, "templates": [...] }` zurück. |
| `POST /meta-templates` | Erstellt eine Vorlage und reicht sie in einem Schritt zur Prüfung bei Meta ein. Erfordert `name`, `language` und `body` (oder ein vollständiges `components`-Array anstelle von `body`). Optional: `variables` (Array von Strings), `category` (`MARKETING`, `UTILITY` oder `AUTHENTICATION`), `header`, `footer`, `buttons`. Gibt `201` mit `{ "success": true, "template": {...} }` zurück. |
| `DELETE /meta-templates/{name}` | Löscht die Vorlage anhand ihres Meta-Namens – **in jeder Sprache**. Fügen Sie `?hsm_id=` mit der Vorlagen-ID von Meta hinzu, um nur eine einzelne Sprache zu entfernen. Gibt `{ "success": true, "name": "..." }` zurück. |

Eine Vorlage, die von Meta abgelehnt wurde, gibt `400` mit der eigenen Erläuterung von Meta in `error` zurück.

---

## Vorlagen auflisten

Gibt alle Vorlagen in Ihrem Konto mit einer kompakten Zusammenfassung jeder Vorlage zurück.

`GET /whatsapp-templates`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/whatsapp-templates?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Antwort**

```json
{
  "success": true,
  "data": [
    {
      "id": "template_abc123",
      "name": "welcome_message",
      "status": "approved",
      "language": "en",
      "body": "Hi {{first_name}}, thanks for reaching out!"
    },
    {
      "id": "template_def456",
      "name": "appointment_reminder",
      "status": "pending",
      "language": "en",
      "body": "Hi {{first_name}}, this is a reminder about your appointment."
    }
  ]
}
```

---

## Eine Vorlage abrufen

Gibt die vollständigen Details einer einzelnen Vorlage zurück, einschließlich ihrer Variablen, ihres Status und ihrer Zeitstempel.

`GET /whatsapp-templates/{templateId}`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Antwort**

```json
{
  "success": true,
  "template": {
    "id": "template_abc123",
    "name": "welcome_message",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "language": "en",
    "variables": ["first_name"],
    "status": "approved",
    "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "type": "general",
    "category": "marketing",
    "rejection_reason": null,
    "campaign_id": "campaign123",
    "date_created": "2026-06-01T10:00:00.000Z",
    "date_updated": "2026-06-02T08:30:00.000Z",
    "submitted_at": "2026-06-01T10:05:00.000Z",
    "approved_at": "2026-06-02T08:30:00.000Z"
  }
}
```

Eine Vorlage, die nicht in Ihrem Konto existiert, gibt `404` mit `{ "success": false, "error": "Template not found" }` zurück.

---

## Vorlage erstellen

Erstellt eine Vorlage für die Eröffnungsnachricht einer Kampagne und reicht sie in einem Schritt zur Genehmigung ein.

`POST /whatsapp-templates`

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `campaign_id` | Ja | Die Kampagne, zu der die Vorlage gehört. |
| `name` | Ja | Ein Name für die Vorlage. |
| `language` | Ja | Sprachcode, zum Beispiel `en`, `es`, `de`, `pt_BR`, `zh_CN`. |
| `body` | Ja | Der Nachrichtentext, bis zu 1024 Zeichen. |
| `variables` | Nein | Geordnete Liste der im Textkörper verwendeten Variablennamen. |

Variablen-Platzhalter können als `{{first_name}}`, `{first_name}` oder `[first_name]` geschrieben werden – sie werden alle in die Form mit doppelten geschweiften Klammern normalisiert.

Das Ergebnis hängt von den Kanälen der Kampagne ab:

- **WhatsApp Business API-Kampagne:** Der Inhalt wird zur WhatsApp-Überprüfung gesendet. Die Antwort enthält `campaign_status` (`received` oder `pending`) und einen `template_sid`.
- **Ein Kanal ohne externen Überprüfungsschritt:** Die Vorlage wird gespeichert und automatisch genehmigt (`campaign_status: "approved"`, `template_sid: null`).
- **Kein WhatsApp-Kanal in der Kampagne:** Es wird nichts erstellt und `campaign_status` ist `not_applicable`.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"]
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
    },
)
data = res.json()
```

**Antwort** (zur Überprüfung eingereicht)

```json
{
  "success": true,
  "campaign_status": "pending",
  "template_sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
```

---

## Erstellen einer eigenständigen Vorlage

Erstellt eine Vorlage in Ihrer Vorlagenbibliothek, ohne sie an die Eröffnungsnachricht einer Kampagne zu binden. Dies ist der Erstellungsschritt des Lebenszyklus, dem der Rest dieser Seite folgt: hier erstellen, bearbeiten, zur Überprüfung einreichen, den Status abfragen und löschen, wenn Sie sie nicht mehr benötigen.

`POST /whatsapp-templates/docs`

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `name` | Ja | Ein Name für die Vorlage. |
| `language` | Ja | Sprachcode, zum Beispiel `en`, `es`, `de`, `pt_BR`, `zh_CN`. |
| `body` | Ja | Der Nachrichtentext, bis zu 1024 Zeichen. |
| `variables` | Nein | Geordnete Liste der im Text verwendeten Variablennamen. |
| `status` | Nein | `draft` (Standard) speichert sie ohne Einreichung; `submitted` stellt sie sofort für die WhatsApp-Überprüfung in die Warteschlange. |
| `type` | Nein | `general` (Standard) oder `smart_followup`. |
| `category` | Nein | `marketing`, `utility`, `authentication` oder `authentication-international`. |
| `campaign_id` | Nein | Verknüpft die Vorlage mit einer Ihrer Kampagnen. |

> **Vorlagen für die Authentifizierung (Einmalcode).** WhatsApp akzeptiert keine frei formulierbaren Authentifizierungsvorlagen: Der Nachrichtentext ist von WhatsApp vorgegeben und die Vorlage muss eine „Code kopieren“-Schaltfläche enthalten. Wenn Sie eine Vorlage mit `category: "authentication"` erstellen, übermitteln wir diese in dieser festen Form für Sie. Ihr `body` wird als Vorschau in der App beibehalten, aber der Text, den Ihr Kontakt erhält, entspricht dem Wortlaut von WhatsApp (der Code, ein Sicherheitshinweis und ein Hinweis auf die 10-minütige Gültigkeitsdauer). Deklarieren Sie genau eine Variable, zum Beispiel `["code"]`, und übergeben Sie den Code beim Senden (siehe das Feld `variables` unter [Senden einer Vorlage an einen Kontakt](#send-a-template-to-a-contact)). Der Code muss kürzer als 15 Zeichen sein.

> **Welche Erstellungsmethode sollte ich verwenden?** Verwenden Sie diese, wenn Sie eine Vorlage wünschen, die Sie selbst bearbeiten und einreichen können. Verwenden Sie `POST /whatsapp-templates` (oben), wenn Sie die Eröffnungsnachricht einer Kampagne festlegen möchten – diese erfordert `campaign_id` und schreibt direkt in die Kampagne.

Eine als `submitted` erstellte Vorlage wird im Hintergrund zur WhatsApp-Überprüfung gesendet. Überprüfen Sie daher den Status-Endpunkt auf das Ergebnis, anstatt es in der Antwort zu erwarten.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/docs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"],
    "status": "draft",
    "category": "marketing"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/docs", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
    status: "draft",
    category: "marketing",
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/docs",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
        "status": "draft",
        "category": "marketing",
    },
)
data = res.json()
```

**Antwort**

```json
{
  "success": true,
  "template_id": "template_abc123",
  "status": "draft"
}
```

Ein fehlendes `name`, `language` oder `body`, eine nicht unterstützte Sprache, ein `status`, der nicht `draft` oder `submitted` ist, ein unbekannter `type` oder `category` oder ein Textkörper mit mehr als 1024 Zeichen führt zu `400` mit einer erklärenden `error`. Eine `campaign_id`, die keine Ihrer Kampagnen ist, führt zu `404`.

---

## Vorlage aktualisieren

Bearbeitet eine Vorlage, die noch nicht genehmigt wurde. Nur Vorlagen mit dem Status `draft` oder `rejected` können bearbeitet werden. Geben Sie eine beliebige Kombination aus `name`, `body`, `language` und `variables` an – nur die Felder, die Sie senden, werden geändert.

`PUT /whatsapp-templates/{templateId}`

> Das Bearbeiten reicht die Vorlage **nicht** erneut zur Überprüfung ein. Verwenden Sie anschließend den Submit-Endpunkt.

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi {{first_name}}, here is an update for you.",
    "variables": ["first_name"]
  }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      body: "Hi {{first_name}}, here is an update for you.",
      variables: ["first_name"],
    }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "body": "Hi {{first_name}}, here is an update for you.",
        "variables": ["first_name"],
    },
)
data = res.json()
```

**Antwort**

```json
{
  "success": true,
  "template_id": "template_abc123"
}
```

Der Versuch, eine Vorlage zu bearbeiten, die bereits `approved` ist (oder anderweitig nicht bearbeitet werden kann), das Senden von leeren Feldern oder das Senden eines ungültigen Wertes führt zu `400` mit einer erklärenden `error`.

---

## Vorlage zur Genehmigung einreichen

Reicht eine `draft` oder `rejected` Vorlage zur Überprüfung ein. Vorlagen für einen Kanal, der keine externe Überprüfung erfordert, werden sofort genehmigt; alle anderen werden an WhatsApp gesendet und die zurückgegebene `status` (normalerweise `received` oder `pending`) wird in der Vorlage gespeichert.

`POST /whatsapp-templates/{templateId}/submit`

> **Follow-up-Vorlagen** müssen ihre erforderlichen Variablen deklarieren und verwenden, bevor sie eingereicht werden können: einen Platzhalter für den Vornamen sowie einen Platzhalter für den persönlichen Kontext bei intelligenten Follow-ups.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Antwort**

```json
{
  "success": true,
  "template_id": "template_abc123",
  "status": "pending",
  "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
```

---

## Genehmigungsstatus prüfen

Ein schlanker Endpunkt zum Abrufen des aktuellen Status einer Vorlage. Der Status wird aus dem gespeicherten Datensatz gelesen, der im Hintergrund regelmäßig aktualisiert wird. Daher kann es eine kurze Zeit dauern, bis eine sehr aktuelle Genehmigung oder Ablehnung angezeigt wird.

`GET /whatsapp-templates/{templateId}/status`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Antwort**

```json
{
  "success": true,
  "template_id": "template_abc123",
  "name": "welcome_message",
  "status": "approved",
  "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "rejection_reason": null,
  "date_updated": "2026-06-02T08:30:00.000Z"
}
```

---

## Vorlage löschen

Entfernt den Vorlagendatensatz aus Ihrem Konto.

`DELETE /whatsapp-templates/{templateId}`

::: warning
**Wichtig:** Bei einer verwalteten Verbindung wird nur der gespeicherte Datensatz entfernt – Inhalte, die WhatsApp bereits genehmigt hat, können weiterhin beim Messaging-Anbieter registriert bleiben. Bei einem Konto, das über ein eigenes WhatsApp Business-Konto läuft, wird die Vorlage auch aus diesem Konto gelöscht. In jedem Fall gilt: Wenn eine Kampagne diese Vorlage noch verwendet, weisen Sie diese Kampagne **vor** dem Löschen einer anderen Vorlage zu, da andernfalls darauf basierende Sendungen fehlschlagen.:::


**cURL**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Antwort**

```json
{
  "success": true,
  "template_id": "template_abc123",
  "note": "The template record was removed from your account. Content already approved by WhatsApp may remain registered with the messaging provider."
}
```

---

## Senden einer Vorlage an einen Kontakt

Sendet eine genehmigte Vorlage an einen Kontakt, auch wenn kein offenes Gespräch besteht — dies öffnet die Chat-Sitzung erneut. Sie können den Kontakt über `contactId` oder `phoneNumber` adressieren und die Vorlage über `whatsappTemplateId` oder `templateName` auswählen.

`POST /whatsapp-templates/send`

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `contactId` | Eines von beiden | Die ID des Kontakts. |
| `phoneNumber` | Eines von beiden | Die Telefonnummer des Kontakts (mit Ländervorwahl, ohne Leerzeichen). Wird bei Bedarf nachgeschlagen oder erstellt. |
| `whatsappTemplateId` | Eines von beiden | Die ID der Vorlage. |
| `templateName` | Eines von beiden | Der Name der Vorlage, wie er in der App angezeigt wird. |
| `firstName` | Nein | Wird zum Ausfüllen eines neu erstellten Kontakts verwendet. |
| `lastName` | Nein | Wird zum Ausfüllen eines neu erstellten Kontakts verwendet. |
| `email` | Nein | Wird zum Ausfüllen eines neu erstellten Kontakts verwendet. |
| `variables` | Nein | Explizite Werte für die Variablen der Vorlage, nach Variablennamen sortiert, zum Beispiel `{ "code": "482913" }`. Ein hier angegebener Wert hat Vorrang vor den Feldern des Kontakts für diese Variable; Variablen, die Sie weglassen, werden weiterhin wie unten beschrieben aus dem Kontakt ausgefüllt. Auf diese Weise übergeben Sie einen Einmalcode an eine Authentifizierungsvorlage. |

Der Textkörper der Vorlage unterstützt erweiterte Variablensubstitution:

- **Grundlegende Variablen:** `{{first_name}}`, `{{email}}`, `{{company}}`
- **Standardwerte:** `{{first_name|there}}` zeigt `there` an, wenn das Feld leer ist
- **Transformationen:** `{{company|uppercase}}`, `{{name|lowercase}}`, `{{name|capitalize}}`
- **Kombiniert:** `{{company|Your Company|uppercase}}`

> **Guthaben:** Das Senden einer Vorlage verbraucht Guthaben. Die genauen Kosten hängen vom Land des Empfängers und der Kategorie der Vorlage ab.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "contact123",
    "whatsappTemplateId": "template_abc123"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/send", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contactId: "contact123",
    whatsappTemplateId: "template_abc123",
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/send",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "contactId": "contact123",
        "whatsappTemplateId": "template_abc123",
    },
)
data = res.json()
```

**Antwort**

```json
{
  "success": true,
  "data": "WhatsApp template message sent successfully"
}
```

Eine Anfrage, bei der sowohl ein Kontaktbezeichner als auch beide Vorlagenbezeichner fehlen, gibt `400` zurück. Wenn Ihrem Konto die für den Versand erforderlichen Messaging-Anmeldeinformationen fehlen, lautet die Antwort `403`.

---

## Erstellen oder Aktualisieren einer Live-Vorlage für eine Kampagne

Ein zweites Paar von Endpunkten für die Eröffnungsvorlage einer Kampagne, die eher über den Pfad als über eine `campaign_id` im Body definiert werden. Diese sollten für eine bereits aktive Kampagne verwendet werden: Im Gegensatz zu [Vorlage erstellen](#create-a-template) oben führt eine Aktualisierung hier auch dazu, dass die Follow-up-Entwürfe der Kampagne erneut zur Überprüfung eingereicht werden, sodass die Eröffnungsvorlage und ihre Follow-ups synchron bleiben.

`POST /whatsapp-templates/campaign/{campaignId}` erstellt die Eröffnungsvorlage der Kampagne. `PUT /whatsapp-templates/campaign/{campaignId}` bearbeitet sie – die Kampagne muss bereits über eine Vorlage verfügen, andernfalls wird `400` zurückgegeben.

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `name` | Ja | Ein Name für die Vorlage. |
| `language` | Ja | Sprachcode, zum Beispiel `en`, `es`, `de`, `pt_BR`, `zh_CN`. |
| `body` | Ja | Der Nachrichtentext, bis zu 1024 Zeichen. |
| `variables` | Ja | Geordnete Liste der im Body verwendeten Variablennamen. Übergeben Sie ein leeres Array, wenn die Vorlage keine verwendet. |

**cURL** (erstellen)

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"]
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
    },
)
data = res.json()
```

**Antwort**

```json
{
  "success": true,
  "campaign_status": "pending",
  "template_sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "message": "WhatsApp template created and campaign updated successfully."
}
```

Um zu bearbeiten, ändern Sie die Methode auf `PUT` und verwenden Sie dieselben Felder – dies reicht die Eröffnungsvorlage (und bei einer WhatsApp-API-Kampagne die Follow-up-Entwürfe der Kampagne) erneut zur Überprüfung ein.

Eine Kampagne, die nicht zu Ihrem Konto gehört, gibt `404` zurück; eine Kampagne, die zu einem anderen Konto gehört, für das Sie nicht autorisiert sind, gibt `403` zurück. Das Bearbeiten einer Kampagne ohne vorhandene Vorlage gibt `400` zurück.

---

## Senden einer Vorlage an einen bestehenden Kontakt

Eine einfachere, pfadbasierte Alternative zu [Vorlage an einen Kontakt senden](#send-a-template-to-a-contact) oben: Sowohl die Vorlage als auch der Kontakt müssen bereits existieren – es wird nichts anhand des Namens gesucht oder spontan erstellt.

`POST /whatsapp-templates/{templateId}/send-to-contact`

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `contactId` | Ja | Die ID des Kontakts. Muss zu Ihrem Konto gehören. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": "contact123" }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactId: "contact123" }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactId": "contact123"},
)
data = res.json()
```

**Antwort**

```json
{
  "success": true,
  "data": "WhatsApp template message sent successfully"
}
```

> **Guthaben:** Das Senden verbraucht Guthaben, das genauso berechnet wird wie beim Endpunkt oben. Eine `contactId`, die fehlt oder nicht zu Ihrem Konto gehört, gibt `403` zurück; ein `templateId`, der nicht existiert, gibt `404` zurück.

---

## Massenversand einer Vorlage

Senden Sie eine Vorlage in einem einzigen Aufruf an viele Kontakte, mit einer Kostenvorschau, die Sie vor der Bestätigung anzeigen können.

### Zuerst die Kosten schätzen

Gibt die Kosten für den Versand aufgeschlüsselt nach Zielland zurück, ohne etwas zu versenden oder Credits zu verbrauchen. Die Vorlagenpreise gelten pro Zielland, daher muss dies serverseitig anhand der tatsächlichen Kontakte berechnet werden, anstatt es clientseitig zu schätzen.

`POST /whatsapp-templates/{templateId}/estimate-bulk-cost`

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `contactIds` | Ja | Zu bepreisende Kontakte, bis zu 500 pro Aufruf. Duplikate werden nur einmal gezählt. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contact123", "contact456"] }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactIds: ["contact123", "contact456"] }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contact123", "contact456"]},
)
data = res.json()
```

**Antwort**

```json
{
  "success": true,
  "data": {
    "countries": [
      {
        "countryCode": "1",
        "name": "United States",
        "iso": "US",
        "flag": "🇺🇸",
        "contactCount": 120,
        "costPerContact": 0.5,
        "subtotal": 60.0
      }
    ],
    "totalContacts": 120,
    "totalTemplateCost": 60.0,
    "templateCategory": "marketing",
    "skippedContacts": 2
  }
}
```

`skippedContacts` zählt IDs, die fehlten, nicht zu Ihrem Konto gehörten oder keine Telefonnummer enthielten — die Schätzung deckt nur den Rest ab, daher bedeutet ein Wert ungleich Null, dass der tatsächliche Versand weniger Kontakte erreicht als von Ihnen ausgewählt.

### Den Batch versenden

Sendet die Vorlage an jeden Kontakt in der Liste, löst alle intelligenten Variablen pro Kontakt auf und berechnet Credits pro Versand.

`POST /whatsapp-templates/{templateId}/bulk-send`

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `contactIds` | Ja | Kontakte, an die gesendet werden soll, bis zu 5000 pro Aufruf. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contact123", "contact456"] }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactIds: ["contact123", "contact456"] }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contact123", "contact456"]},
)
data = res.json()
```

**Antwort**

```json
{
  "success": true,
  "data": { "sent": 118, "failed": 2, "total": 120 }
}
```

Ein Kontakt, bei dem ein Fehler auftritt (nicht gefunden, nicht in Ihrem Konto oder ein Versandfehler), wird übersprungen und in `failed` gezählt, anstatt den Batch zu stoppen. Ein leeres `contactIds`, mehr als 5000 IDs bei einem Versand (500 bei einer Schätzung) oder ein fehlendes `templateId` führt zu `400`.

---

## Eine fehlgeschlagene Nachricht erneut senden

Zwei Endpunkte für den erneuten Versand einer fehlgeschlagenen Nachricht, ohne einen neuen Nachrichtendatensatz zu erstellen oder erneut Credits zu verbrauchen.

`POST /whatsapp-templates/messages/{contactId}/{messageId}/retry-template` versucht speziell den erneuten Versand einer fehlgeschlagenen Vorlagennachricht — der Vorlageninhalt wird aus der Kampagne neu aufgelöst, falls die fehlgeschlagene Nachricht diesen nicht bereits enthält. Nur Nachrichten mit dem Status `failed` und dem Typ `template` können auf diese Weise erneut gesendet werden.

`POST /whatsapp-templates/messages/{contactId}/{messageId}/retry` ist kanalunabhängig und funktioniert für jede fehlgeschlagene Nicht-Vorlagen-Nachricht (zum Beispiel WhatsApp Web), wobei der Versand basierend auf dem Kanal der Nachricht an den richtigen Pfad weitergeleitet wird. Es akzeptiert den Status `failed`, `failed_connection`, `limit_exceeded` oder `queued_retry`.

Keiner der Endpunkte benötigt einen Request-Body.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Antwort**

```json
{
  "success": true,
  "data": "Message retry initiated successfully"
}
```

Für die kanalunabhängige Version ändern Sie den Pfad zu `.../msg_abc789/retry`. Eine Nachricht, deren Status nicht für einen erneuten Versand qualifiziert ist, oder (beim Vorlagen-Endpunkt) die keine Vorlagennachricht ist, führt zu `400`. Ein fehlender Kontakt oder eine fehlende Nachricht führt zu `404`.

---

## WhatsApp Business-Profil

Verwalten Sie das WhatsApp Business-Profil (Info, Adresse, Beschreibung, E-Mail, Websites, Geschäftskategorie und Logo), das Kontakten auf WhatsApp angezeigt wird. Funktioniert sowohl mit einer verwalteten Verbindung als auch mit einem Konto, das ein eigenes WhatsApp Business-Konto betreibt.

### Profil speichern

`PUT /whatsapp-templates/profile`

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `phoneNumber` | Ja | Die WhatsApp-Nummer, zu der dieses Profil gehört. Muss mit Ihrem Konto verbunden sein. |
| `about` | Nein | Kurzer „Info“-Text, der im Profil angezeigt wird. |
| `address` | Nein | Geschäftsadresse. |
| `description` | Nein | Längere Geschäftsbeschreibung. |
| `email` | Nein | Kontakt-E-Mail, die im Profil angezeigt wird. |
| `websites` | Nein | Array von Website-URLs. Jede muss eine gültige URL sein. |
| `vertical` | Nein | Geschäftskategorie, zum Beispiel `Retail` oder `Professional Services`. |
| `profilePictureHandle` | Nein | Das Handle, das vom unten stehenden Bild-Upload-Endpunkt zurückgegeben wird, um das Profilfoto festzulegen. |

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/whatsapp-templates/profile?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "about": "We reply within a few hours",
    "email": "support@example.com",
    "websites": ["https://example.com"]
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/profile", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+31612345678",
    about: "We reply within a few hours",
    email: "support@example.com",
    websites: ["https://example.com"],
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/whatsapp-templates/profile",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+31612345678",
        "about": "We reply within a few hours",
        "email": "support@example.com",
        "websites": ["https://example.com"],
    },
)
data = res.json()
```

**Antwort**

```json
{
  "success": true,
  "data": "WhatsApp Business profile updated successfully"
}
```

Eine fehlende `phoneNumber`, eine ungültige Website-URL oder eine `phoneNumber`, die nicht mit Ihrem Konto verbunden ist, führt zu `400` oder `404`.

### Profilbild hochladen

Lädt ein Bild von einer von Ihnen bereitgestellten URL herunter und lädt es auf WhatsApp hoch, wobei ein Handle zurückgegeben wird. Übergeben Sie dieses Handle als `profilePictureHandle` beim oben genannten Aufruf zum Speichern des Profils, um es als Foto festzulegen – dieser Endpunkt lädt das Bild nur hoch, er legt es nicht von selbst fest.

`POST /whatsapp-templates/profile/picture`

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `phoneNumber` | Ja | Die WhatsApp-Nummer, zu der dieses Profil gehört. |
| `fileUrl` | Ja | Eine öffentlich erreichbare URL zu dem hochzuladenden Bild. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "fileUrl": "https://example.com/logo.png"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+31612345678",
    fileUrl: "https://example.com/logo.png",
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+31612345678",
        "fileUrl": "https://example.com/logo.png",
    },
)
data = res.json()
```

**Antwort**

```json
{
  "success": true,
  "data": "1234567890123456"
}
```

`data` ist das Handle des hochgeladenen Bildes. Eine fehlende `phoneNumber` oder `fileUrl` oder eine `phoneNumber` ohne hinterlegtes WhatsApp-Zugriffstoken führt zu `400`; eine nicht erreichbare oder ungültige `fileUrl` gibt einen Fehler zurück, der beschreibt, warum der Download fehlgeschlagen ist.

---

## Status eines Absenders prüfen

Fragt den Live-Sendestatus einer verbundenen WhatsApp-Nummer beim Messaging-Anbieter ab (und aktualisiert ihn). Nützlich, um zu bestätigen, dass eine Nummer tatsächlich senden kann, bevor Sie sich darauf verlassen.

`GET /whatsapp-templates/sender-status/{phoneNumber}`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Antwort**

```json
{
  "success": true,
  "data": "ONLINE"
}
```

`data` ist einer der Werte `ONLINE` (sendet normal), `PENDING` (wird noch verifiziert) oder `DELETED` (der Anbieter erkennt diesen Absender nicht mehr – verbinden Sie die Nummer erneut). Eine `phoneNumber` ohne hinterlegte WhatsApp-Geschäftsinformationen führt zu `404`.

---

## Follow-up-Vorlagen mit KI generieren

Die Plattform kann die WhatsApp-Follow-up-Vorlagen für eine Kampagne für Sie schreiben – also die Erinnerungen, die gesendet werden, wenn ein Gespräch einschläft – basierend auf den Anweisungen und dem Ziel der Kampagne. Es gibt einen Job-Endpunkt, der im Hintergrund ausgeführt wird, sowie drei ältere Endpunkte, die für bestehende Integrationen beibehalten wurden. Alle verbrauchen KI-Credits.

### Einen Generierungs-Job starten

`POST /campaigns/{campaignId}/template-generation`

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `type` | Nein | `all` (Standard) schreibt das gesamte Follow-up-Set. `cold_only` schreibt nur die Nachrichten für Kontakte, die nie geantwortet haben. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ type: "all" }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"type": "all"},
)
data = res.json()
```

**Antwort** (`202`)

```json
{ "success": true, "campaign_id": "campaign_abc123", "type": "all" }
```

Der Aufruf kehrt zurück, sobald der Job in die Warteschlange eingereiht wurde. Lesen Sie die Kampagne (`GET /campaigns/{campaignId}`, siehe [Campaigns API](campaigns.md)) und beobachten Sie deren `template_generation_status`-Objekt, bis der Vorgang abgeschlossen ist:

| Feld | Beschreibung |
|---|---|
| `status` | `processing` während der Job läuft, danach `completed` oder `failed`. |
| `progress` | 0 bis 100. |
| `current_template`, `total_templates` | Wie viele Vorlagen bisher geschrieben wurden, von wie vielen der Job insgesamt schreiben wird – 11 für eine ausgehende oder kombinierte Kampagne, ansonsten 9. |
| `error` | Grund, warum ein `failed`-Job gestoppt wurde, zum Beispiel nicht genügend Credits. |
| `started_at`, `completed_at` | Wann der Job begann und endete. |

Die generierten Vorlagen landen wie jede andere auf der Kampagne, erscheinen also unter [Vorlagen auflisten](#list-templates) und durchlaufen weiterhin die WhatsApp-Genehmigung, bevor sie gesendet werden können. Ein `400` bedeutet, dass `type` etwas anderes als `all` oder `cold_only` war; ein `404` bedeutet, dass die Kampagne nicht existiert oder zu einem anderen Konto gehört.

Agenten haben ein Pendant zu diesem Aufruf, `POST /agents/{agentId}/template-generation`, das die Follow-ups für einen Agenten schreibt und im Normalfall während des Aufrufs abgeschlossen wird – siehe [Follow-up-Nachrichten generieren](agents.md#generate-follow-up-messages) in der AI Agents API.

### Die älteren Generierungs-Endpunkte

Drei frühere Endpunkte erledigen dieselbe Arbeit und werden beibehalten, damit bestehende Integrationen weiterhin funktionieren. Neuer Code sollte den oben genannten Job-Endpunkt verwenden.

| Endpunkt | Funktion |
|---|---|
| `POST /whatsapp-templates/campaign/{campaignId}/generate-async` | Startet die Follow-up-Generierung für die Kampagne im Hintergrund und gibt `202` mit `{ "success": true, "data": { "result": "success", "message": "..." } }` zurück. Credits werden im Voraus berechnet (entfällt bei einem Konto, das einen eigenen KI-Schlüssel mitbringt) und das `template_generation_status` der Kampagne meldet den Fortschritt genau wie oben beschrieben. |
| `POST /whatsapp-templates/campaign/{campaignId}/generate-followups` | Generiert alle neun Follow-up-Vorlagen während des Aufrufs – für eine Kampagne, die erstellt wurde, bevor automatische Follow-ups existierten, oder eine, bei der sie neu geschrieben werden müssen – und gibt `200` mit `templatesGenerated` innerhalb von `data` zurück. |
| `POST /whatsapp-templates/agent/{agentId}/generate-followups` | Die gleiche synchrone Generierung, die von Agent adressiert wird. Die Antwort fügt `agent_id`, `campaign_id` und `target` hinzu: `"campaign"`, wenn die Vorlagen auf die Kampagne des Agenten geschrieben wurden, `"agent"` (mit `campaign_id: null`), wenn der Agent keine Kampagne hat und sie auf dem Agenten selbst gespeichert wurden. Ein fehlender oder fremder Agent ist ein `404`. |

Alle drei erfordern automatische Follow-ups auf dem Konto und genügend Credits – ein `400` benennt, was fehlt – und das kampagnenadressierte Paar gibt `403` zurück, wenn die Kampagne zu einem anderen Konto gehört.

---

## Fehler der Templates-API

Template-Endpunkte geben das Standard-Fehler-Envelope zurück:

```json
{
  "success": false,
  "error": "Template not found"
}
```

Ein `404` bei diesen Endpunkten bedeutet normalerweise, dass die Ressource nicht gefunden wurde – entweder existiert sie nicht oder sie gehört zu einem anderen Konto. Einige Endpunkte (das Erstellen/Aktualisieren im Kampagnenkontext und das Senden an einen bestehenden Kontakt) geben stattdessen `403` zurück, wenn die Kampagne oder der Kontakt jemand anderem gehört, anstatt gar nicht zu existieren. Einige Endpunkte enthalten auch ein `error_code`-Feld, das den HTTP-Status widerspiegelt. Die gemeinsamen Codes, die jeder Endpunkt zurückgeben kann – `400`, `401`, `403` (Ihr Plan beinhaltet keinen API-Zugriff), `429` (Ratenbegrenzung) und `500` – sind zusammen mit Hinweisen zur Wiederholung unter [Fehler & Paginierung](errors-and-pagination.md) aufgeführt.

---

## Nächste Schritte

- [Authentifizierung](authentication.md) — die vier Möglichkeiten zur Authentifizierung einer Anfrage.
- [Fehler & Ratenbegrenzungen](errors-and-pagination.md) — Statuscodes und das Limit von 300 Anfragen/Min.
- [Kampagnen-API](campaigns.md) — Verwalten Sie die Kampagnen, denen Vorlagen zugeordnet sind.