> ## Documentation Index
> Fetch the complete documentation index at: https://docs.so-me.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp-Business-Vorlagen in der CLI

> WhatsApp-Business-Nachrichtenvorlagen erstellen, auflisten und löschen sowie Vorlagennachrichten über die Social-media-studio-CLI senden.

Diese Befehle kapseln die API `/v1/whatsapp/*`. Der Umfang ist bewusst schmal gehalten — Lebenszyklus der Vorlagen plus Versand ausgehender Vorlagennachrichten. Die WABA-Verbindung erfolgt ausschließlich im Browser (OAuth) und bleibt im Dashboard.

> [!NOTE]
>
> Alle Befehle akzeptieren an der Stelle `<account-id>` entweder die **interne Social-Konto-UUID** (aus [`accounts:list`](/de/cli/accounts)) oder die **Meta-WABA-Anbieter-ID**. Der v1-Controller löst UUIDs serverseitig in Anbieter-IDs auf.

## whatsapp:templates

Listet jede Vorlage auf, die in einem WhatsApp-Business-Konto registriert ist, einschließlich Status (`APPROVED`, `PENDING`, `REJECTED`), Kategorie, Sprache und Komponentenstruktur.

```bash theme={null}
so-me whatsapp:templates <account-id>
```

| Argument | Beschreibung |
| - | - |
| `<account-id>` | UUID des WhatsApp-Social-Kontos (aus [`accounts:list`](/de/cli/accounts)) oder Meta-WABA-Anbieter-ID **(erforderlich)** |

```bash Beispiele theme={null}
# Vollständige Liste
so-me whatsapp:templates e6be46a2-430a-41df-b180-b51527e954e3

# Nur genehmigte Vorlagen
so-me whatsapp:templates e6be46a2-... | jq '.data[] | select(.status == "APPROVED")'

# Nur Namen + Status in tabellenähnlicher Ansicht
so-me whatsapp:templates e6be46a2-... | jq -r '.data[] | "\(.status)\t\(.name)\t\(.language)"'

# Anbieter-ID statt UUID übergeben
so-me whatsapp:templates 1050417321480811
```

## whatsapp:create-template

Reicht eine neue Vorlage bei Meta zur Genehmigung ein. Die Genehmigung von Vorlagen kann Minuten bis Stunden dauern; frage `whatsapp:templates` ab, um den Statusübergang von `PENDING` → `APPROVED` zu sehen.

```bash theme={null}
so-me whatsapp:create-template --account <id> (--file <path> | --data <json>)
```

| Option | Beschreibung |
| - | - |
| `--account <id>` | WhatsApp-Konto-UUID oder Anbieter-ID **(erforderlich)** |
| `-f, --file <path>` | JSON-Datei mit der vollständigen Vorlagendefinition |
| `-d, --data <json>` | JSON-String mit der vollständigen Vorlagendefinition |

Übergib die Vorlagendefinition **entweder** mit `--file` **oder** mit `--data` (werden beide angegeben, gewinnt `--file`; wird keines angegeben, gibt der Befehl einen Fehler aus). Die Payload entspricht dem Schema der WhatsApp Cloud API von Meta. Mindestfelder:

* `name` — Kleinbuchstaben, mit Unterstrichen
* `language` — z. B. `en_US`
* `category` — `MARKETING`, `UTILITY` oder `AUTHENTICATION`
* `components[]` — `HEADER`, `BODY`, `FOOTER`, `BUTTONS`

Die CLI fügt `accountId` (aus `--account`) vor dem Absenden in die Payload ein, du musst es also nicht im JSON angeben.

```json theme={null}
{
  "name": "order_shipped",
  "language": "en_US",
  "category": "UTILITY",
  "components": [
    { "type": "HEADER", "format": "TEXT", "text": "Order update" },
    { "type": "BODY", "text": "Hi {{1}}, your order #{{2}} has shipped." },
    { "type": "FOOTER", "text": "Thanks for shopping with us!" }
  ]
}
```

```bash Beispiele theme={null}
# Aus einer Datei
so-me whatsapp:create-template --account e6be46a2-... --file ./order_shipped.json

# Inline
so-me whatsapp:create-template --account e6be46a2-... --data '{
  "name": "welcome_v1",
  "language": "en_US",
  "category": "MARKETING",
  "components": [{ "type": "BODY", "text": "Welcome, {{1}}!" }]
}'
```

> [!WARNING]
>
> Vorlagennamen müssen aus Kleinbuchstaben, Ziffern und Unterstrichen bestehen (`^[a-z0-9_]+$`). Meta validiert das — nicht passende Namen werden sofort mit 400 abgelehnt.

## whatsapp:delete-template

Löscht eine Vorlage dauerhaft. Nach dem Löschen kann sie nicht wiederhergestellt werden; du musst sie unter einem neuen Namen erneut einreichen.

```bash theme={null}
so-me whatsapp:delete-template <account-id> <template-name> [-y]
```

| Argument | Beschreibung |
| - | - |
| `<account-id>` | WhatsApp-Social-Konto-UUID oder Anbieter-ID **(erforderlich)** |
| `<template-name>` | Vorlagenname (`lowercase_underscored`) **(erforderlich)** |

| Option | Beschreibung |
| - | - |
| `-y, --yes` | Bestätigungsabfrage überspringen |

Ohne `-y` fragt der Befehl `Delete template "<name>" on account <id>? (y/N)` und bricht ab, sofern du nicht mit `y` antwortest.

```bash Beispiele theme={null}
# Mit Bestätigung
so-me whatsapp:delete-template e6be46a2-... old_template

# Abfrage überspringen
so-me whatsapp:delete-template e6be46a2-... old_template -y

# Jede REJECTED-Vorlage löschen (Vorsicht)
so-me whatsapp:templates e6be46a2-... \
  | jq -r '.data[] | select(.status == "REJECTED") | .name' \
  | xargs -I {} so-me whatsapp:delete-template e6be46a2-... {} -y
```

## whatsapp:send

Sendet eine genehmigte Vorlagennachricht an einen Empfänger. Das ist der wichtigste Weg, eine WhatsApp-Konversation außerhalb des 24-Stunden-Kundenservice-Fensters zu **eröffnen**.

```bash theme={null}
so-me whatsapp:send <account-id> --to <phone> --template <name> --language <code> [--components <json>]
```

| Argument | Beschreibung |
| - | - |
| `<account-id>` | WhatsApp-Social-Konto-UUID oder Anbieter-ID **(erforderlich)** |

| Option | Beschreibung |
| - | - |
| `--to <phone>` | Empfänger im E.164-Format (z. B. `+15551234567`) **(erforderlich)** |
| `--template <name>` | Name einer APPROVED-Vorlage **(erforderlich)** |
| `--language <code>` | Sprachcode (z. B. `en_US`, `es`, `pt_BR`) **(erforderlich)** |
| `--components <json>` | Vorlagenparameter als Inline-JSON-String |
| `--file <path>` | Vorlagenparameter aus einer JSON-Datei |

`--components` und `--file` sind beide optional (eine Vorlage ohne Variablen braucht keines von beiden). Werden beide angegeben, hat `--file` Vorrang.

Komponentenparameter füllen die Variablen (`{{1}}`, `{{2}}` usw.) der genehmigten Vorlage. Das Format entspricht der Cloud API von Meta:

```json theme={null}
[
  {
    "type": "body",
    "parameters": [
      { "type": "text", "text": "Alice" },
      { "type": "text", "text": "1234" }
    ]
  }
]
```

```bash Beispiele theme={null}
# Vorlage ohne Variablen
so-me whatsapp:send e6be46a2-... \
  --to +15551234567 --template welcome_v1 --language en_US

# Vorlage mit Body-Variablen
so-me whatsapp:send e6be46a2-... \
  --to +15551234567 --template order_shipped --language en_US \
  --components '[{"type":"body","parameters":[{"type":"text","text":"Alice"},{"type":"text","text":"ORD-1234"}]}]'

# Parameter aus einer Datei (einfacher bei komplexen Komponenten)
so-me whatsapp:send e6be46a2-... \
  --to +15551234567 --template order_shipped --language en_US \
  --file ./order_components.json

# Broadcast-Schleife (beachte die Nachrichten-Ratenlimits von Meta)
while read -r phone name; do
  so-me whatsapp:send e6be46a2-... \
    --to "$phone" --template welcome_v1 --language en_US \
    --components "[{\"type\":\"body\",\"parameters\":[{\"type\":\"text\",\"text\":\"$name\"}]}]"
done < recipients.tsv
```

> [!WARNING]
>
> Der Versand von Vorlagen wird gemäß der WhatsApp-Business-Preisgestaltung von Meta abgerechnet. Teste immer zuerst mit einem einzelnen Empfänger. Nicht genehmigte oder abgelehnte Vorlagen schlagen mit 400 fehl.

## whatsapp:upload-media

Lädt Header-Medien (Bild/Video/Dokument) zur Verwendung in der `HEADER`-Komponente einer Vorlage hoch. Gibt ein Medien-Handle zurück, das du beim Erstellen oder Senden von Vorlagen referenzieren kannst.

```bash theme={null}
so-me whatsapp:upload-media --account <id> --type <fileType> (--url <url> | --base64 <content>)
```

| Option | Beschreibung |
| - | - |
| `--account <id>` | WhatsApp-Konto-UUID oder Anbieter-ID **(erforderlich)** |
| `--type <fileType>` | Dateityp: `image`, `video` oder `document` **(erforderlich)** |
| `--url <url>` | Öffentliche URL des hochzuladenden Mediums |
| `--base64 <content>` | Base64-kodierter Dateiinhalt (Alternative zu `--url`) |

Gib genau eines von `--url` oder `--base64` an — der Befehl gibt einen Fehler aus, wenn du keines oder beide angibst.

```bash Beispiele theme={null}
# Von einer öffentlichen URL
so-me whatsapp:upload-media \
  --account e6be46a2-... --type image \
  --url https://cdn.example.com/hero.jpg

# Aus einer lokalen Datei (base64-kodiert)
so-me whatsapp:upload-media \
  --account e6be46a2-... --type image \
  --base64 "$(base64 -w0 ./hero.jpg)"
```

## Das große Ganze

* **Session-Nachrichten** (Antworten innerhalb von 24 Stunden nach einer eingehenden Nachricht) laufen über [`inbox:reply`](/de/cli/inbox) — keine Vorlage erforderlich.
* **Vorlagennachrichten** (Erstkontakt oder außerhalb des 24-Stunden-Fensters) verwenden `whatsapp:send` und erfordern eine von Meta genehmigte Vorlage.
* **Das Verbinden eines WhatsApp-Business-Kontos** erfolgt weiterhin ausschließlich im Browser — schließe zuerst OAuth im [Dashboard](https://so-me.studio/de) ab, dann können deine CLI-Skripte auf das verbundene Konto verweisen.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.