# Listen

Mit den Methoden dieses Bereichs erstellen und löschen Sie [Listen](https://support.watbot.org/de/lists), ändern ihre Felder und verwalten Einträge: Sie legen sie an, lesen, ändern und löschen sie. So kann zum Beispiel Ihre Website die Liste „Speisekarte des Cafés“ selbst aktuell halten, und der Bot zeigt sie den Menschen.

## Wie eine Liste aufgebaut ist

Eine Liste besteht aus zwei Teilen:

- **Schema** — der Name der Liste und ihre Felder. Damit arbeiten die Methoden auf der Seite [Listen und Felder](https://support.watbot.org/de/api/lists/schemas). In den Methodennamen heißt das Schema genau so: `getListSchema`, `createListSchema`.
- **Einträge** — die Zeilen der Liste mit den Feldwerten. Damit arbeiten die Methoden auf der Seite [Einträge](https://support.watbot.org/de/api/lists/items).

Listen gehören zu einem Projekt. Eine Liste kann im Projekt oder in einem Bot erstellt werden — dann landet sie ebenfalls im Projekt dieses Bots. Über die API sind alle Listen der Projekte zugänglich, deren Inhaber der Schlüsselinhaber ist: sowohl die in Bots erstellten als auch die direkt im Projekt erstellten.

## Kennungen

| Was | Wie es aussieht | Woher Sie es bekommen |
|---|---|---|
| Liste (`schema_id`, `id` in Antworten) | Zeichenkette aus 24 Zeichen: `6650a1f2c3d4e5f6a7b8c9d0` | Antworten von `getListSchemas` und `createListSchema` |
| Eintrag (`item_id`, `id` in Antworten) | Zeichenkette aus 24 Zeichen, wie bei einer Liste | Antworten von `getListItems` und `addListItem` |
| Feld (`slug`) | Buchstaben, Ziffern, `-` und `_`, am besten lateinisch: `preis` | Schlüssel des Objekts `fields` in der Antwort von `getListSchema` |
| Projekt (`project_uuid`, `project` in Antworten) | UUID: `3f2b8c1e-…` | Adresse des Projekts im Konto: `/projects/<uuid>/…` |
| Bot (`bot_id`) | Zahl | Adresse des Bots im Konto: `/bots/12345/…` |
| Kontakt | Zahl | Die Kontakt-Methoden |

Der `slug` ist der [Name des Feldes in Platzhaltern](https://support.watbot.org/de/lists/create#name-des-feldes-in-platzhaltern): Unter ihm liegt der Wert im Eintrag, und unter ihm lesen ihn auch die Blöcke des Bots. Felder, die im Konto erstellt werden, erhalten ihn automatisch; über die API legen Sie ihn selbst fest.

## Feldtypen

Der Typ wird beim Erstellen des Feldes im Parameter `type` festgelegt und lässt sich später nicht ändern.

| `type` | Typ im Konto | Was Sie übergeben | Was zurückkommt |
|---|---|---|---|
| `string` | „Text“ | Eine Zeichenkette | Eine Zeichenkette |
| `number` | „Zahl“ | Eine Zahl oder eine Zeichenkette mit einer Zahl: `12`, `"4.5"` | Eine Zahl |
| `bool` | „Logisch“ | `true` oder `false` (auch `1` und `0`) | `true` oder `false` |
| `date` | „Datum“ | Ein Datum in einem gängigen Format: `"2026-10-15"` | Datum und Uhrzeit in UTC: `"2026-10-15T00:00:00.000000Z"` |
| `datetime` | „Datum und Uhrzeit“ | Datum und Uhrzeit: `"2026-10-15 14:30"` oder `"2026-10-15T14:30:00+02:00"` | Datum und Uhrzeit in UTC |
| `money` | „Geldbetrag“ | Einen Betrag in Euro, Dollar usw.: `3.9` oder `12.99` | Den Betrag in denselben Einheiten: `3.9` |
| `file` | „Datei“ | Ein Objekt mit einem Link — siehe unten | Ein Objekt mit der Beschreibung der Datei |
| `image` | „Bild“ | Ein Objekt mit einem Link — siehe unten | Ein Objekt mit der Beschreibung der Datei |
| `contact` | „Kontakt-ID“ | Die ID eines Kontakts | Die ID des Kontakts |
| `bot` | „Bot-ID“ | Die ID eines Bots | Die ID des Bots |

Ein leeres Feld kommt in der Antwort als `null` zurück.

### Datum und Uhrzeit

Eine Uhrzeit ohne Zeitzone gilt als UTC: `"2026-10-15 14:30"` wird als 14:30 UTC gespeichert. Um eine Ortszeit zu übergeben, geben Sie die Zeitzone an: `"2026-10-15T14:30:00+02:00"`. Ein `date`-Feld schneidet die Uhrzeit nicht ab: Wenn Sie ein Datum mit Uhrzeit übergeben, bleibt die Uhrzeit erhalten.

### Geldbeträge

Die Währung wird beim Anlegen des Feldes festgelegt (`currency`) und im Eintrag nicht übergeben. Das ist ein dreibuchstabiger Code nach ISO 4217: `EUR`, `USD`, `CHF`. In `createListSchema` kann die Währung fehlen — dann gilt `USD`; in `addListSchemaField` ist sie Pflicht. Ein unbekannter Code — `422`.

Übergeben Sie Beträge in Haupteinheiten — in Euro, nicht in Cent. Der Betrag wird auf die Nachkommastellen der Währung gerundet (beim Euro und beim Dollar zwei), die Hälfte aufwärts: `0.295` wird als `0.30` gespeichert.

### Dateien und Bilder

Der Wert eines `file`- oder `image`-Feldes ist ein Objekt. Über die API können Sie darin nur einen Link auf eine Datei speichern, die im Internet liegt:

```json
{
  "url": "https://example.com/karte/cappuccino.jpg",
  "storage": "url",
  "name": "cappuccino.jpg",
  "type": "image"
}
```

| Schlüssel | Pflicht | Beschreibung |
|---|---|---|
| `url` | ja | Ein Link mit `http://` oder `https://` |
| `storage` | ja | Immer `"url"` |
| `name` | nein | Dateiname |
| `type` | nein | Art der Datei: `image`, `video`, `audio` oder `document` |
| `mime_type` | nein | MIME-Typ: `image/jpeg` |
| `size` | nein | Größe in Byte |
| `caption` | nein | Bildunterschrift |

> [!WARNING]
> Ohne `"storage": "url"` oder mit einem Link anderer Art (nicht `http`/`https`) wird der Wert stillschweigend nicht gespeichert — im Feld steht dann `null`, eine Fehlermeldung gibt es nicht.

Andere Schlüssel (etwa `uuid` oder `path`) werden ignoriert: Im Feld wird nur der externe Link gespeichert, und die Antwort gibt ihn genau so zurück, wie Sie ihn übergeben haben. Einen Link auf eine Datei im Speicher der Plattform — solche Links enthalten die Antworten für Dateien, die in Ihrem Konto hochgeladen wurden — können Sie nur innerhalb Ihres eigenen Kontos speichern; ein Link auf die Datei eines anderen Kontos wird nicht gespeichert, im Feld steht dann `null`. Übergeben Sie in `updateListItem` die Datei, die schon im Eintrag liegt, zum Beispiel einen ganzen Eintrag aus `getListItems`, bleibt sie unverändert.

In Antworten wird eine Datei durch ein Objekt mit den Schlüsseln `type`, `mime_type`, `created_at`, `name`, `size`, `storage`, `caption`, `meta` (Breite, Höhe, Dauer, Codec) und `url` beschrieben. Links auf Dateien, die im Konto hochgeladen wurden, sind zeitlich begrenzt: Laden Sie die Datei sofort herunter oder fragen Sie den Eintrag erneut ab.

### Kontakt und Bot

In die Felder `contact` und `bot` wird eine ID übergeben. Der Kontakt muss zu Ihrem Bot gehören und der Bot Ihnen, sonst lautet die Antwort `403`. Eine nicht existierende ID besteht die Prüfung nicht — `422`.

Neben dem Wert des Feldes selbst erhält der Eintrag die internen Schlüssel `contact_id` oder `bot_id` — nach ihnen filtert [`getListItems`](10-items.md#getlistitems). Hat eine Liste mehrere solcher Felder, steht dort der Wert des letzten davon.

## Feldeinstellungen

| Parameter | Typ | Standard | Beschreibung |
|---|---|---|---|
| `is_required` | Boolean | `true` | „Pflichtfeld“: Ohne Wert wird der Eintrag nicht angelegt |
| `is_hidden` | Boolean | `false` | „Feld in der Oberfläche ausblenden“: Das Feld ist in der Tabelle der Einträge im Konto nicht zu sehen. Die API gibt es wie gewohnt zurück |
| `is_encryptable` | Boolean | `false` | „Feld verschlüsseln“: Der Wert wird verschlüsselt gespeichert. Die API gibt ihn entschlüsselt zurück. Im Konto gibt es die Verschlüsselung nur bei den Typen `string` und `number` — setzen Sie sie nur bei diesen. Nach verschlüsselten Feldern lässt sich nicht filtern |

> [!IMPORTANT]
> Ein über die API erstelltes Feld ist standardmäßig ein Pflichtfeld — anders als im Konto. Wenn ein Feld leer bleiben darf, übergeben Sie `"is_required": false`.

## Einschränkungen

- Pro Projekt höchstens 5000 Listen.
- Beim Erstellen einer Liste 1 bis 30 Felder.
- Namen von Listen und Feldern — bis zu 255 Zeichen.
- Interne Feldnamen sind nicht erlaubt: `id`, `_id`, `contact`, `contact_id`, `bot`, `bot_id`, `user`, `user_id`, `project`, `project_id`, `data`, `schema_id`, `created_at`, `updated_at`, `deleted_at` sowie alle Namen, die mit `__` beginnen. Auf einen solchen `slug` antwortet die API mit `422` und dem Text „The slug is reserved.“.

Allgemeine Regeln — Schlüssel, Anfragehäufigkeit, Fehlercodes — finden Sie auf der Seite [API](https://support.watbot.org/de/api#fehler).

## Methoden

| Methode | Was sie tut |
|---|---|
| [`getListSchemas`](05-schemas.md#getlistschemas) | Alle Listen Ihrer Projekte |
| [`getListSchema`](05-schemas.md#getlistschema) | Eine Liste mit ihren Feldern |
| [`createListSchema`](05-schemas.md#createlistschema) | Liste erstellen |
| [`deleteListSchema`](05-schemas.md#deletelistschema) | Liste löschen |
| [`addListSchemaField`](05-schemas.md#addlistschemafield) | Feld hinzufügen |
| [`deleteListSchemaField`](05-schemas.md#deletelistschemafield) | Feld löschen |
| [`getListItems`](10-items.md#getlistitems) | Einträge einer Liste mit Filter und Sortierung |
| [`addListItem`](10-items.md#addlistitem) | Eintrag anlegen |
| [`updateListItem`](10-items.md#updatelistitem) | Eintrag ändern |
| [`deleteListItem`](10-items.md#deletelistitem) | Eintrag löschen |