Listen#

Mit den Methoden dieses Bereichs erstellen und löschen Sie Listen, ä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. 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.

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#

Der slug ist der 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.

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:

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

Achtung

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. Hat eine Liste mehrere solcher Felder, steht dort der Wert des letzten davon.

Feldeinstellungen#

Wichtig

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.

Methoden#