Kontakte

Ein Kontakt ist eine Person, die einem Bot in einem Messenger oder im Chat auf einer Website schreibt. Mit den Methoden auf dieser Seite exportieren Sie die Kontakte Ihrer Bots — etwa, um sie in ein CRM zu übernehmen —, zählen sie und legen einen Kontakt aus Ihrem eigenen System an, wenn Sie die Messenger-ID der Person bereits kennen. Mehr zu Kontakten im Dashboard unter Kontakte.

Die Ausgabe lässt sich auf zwei Arten durchblättern: seitenweise (page und count, bis zu 500 Kontakte pro Anfrage) oder mit Versatz vom Anfang (offset und limit, bis zu 1000 Kontakte pro Anfrage). Wie viele Kontakte passen, verrät getNumberOfContacts.

Die Methoden liefern nur Kontakte Ihrer eigenen Bots. Kontakte, die beim Testen eines Bots in der Vorschau entstanden sind, werden weder exportiert noch gezählt.

Kontaktfelder

Alle Methoden, die Kontakte liefern — hier und auf der Seite Eingeladene —, geben sie in derselben Form zurück.

Feld	Typ	Beschreibung
`id`	Zahl	Kontakt-ID
`bot_id`	Zahl	Bot-ID
`phone`	String oder `null`	Telefonnummer, wenn der Kontakt sie geteilt hat oder sie über die API gesetzt wurde
`email`	String oder `null`	E-Mail
`name`	String	Name
`address`	String oder `null`	Adresse
`messenger`	String	Herkunft des Kontakts: `telegram`, `max`, `viber`, `vk` oder `web` (Chat auf der Website)
`utm`	Objekt	Variablen des Kontakts, deren Name mit `utm_` beginnt: `{"utm_source": "…"}`. Gibt es keine, ein leeres Array `[]`
`avatar`	String oder `null`	Link zum Foto des Kontakts. Ein Link auf eine Datei im Speicher ist befristet — speichern Sie die Datei selbst, nicht den Link
`telegram_id`	String	Telegram-Benutzer-ID. Nur bei Telegram-Kontakten
`telegram_username`	String oder `null`	Telegram-Benutzername ohne `@`. Nur bei Telegram-Kontakten
`max_user_id`	Zahl	MAX-Benutzer-ID. Nur bei MAX-Kontakten
`max_username`	String oder `null`	MAX-Benutzername. Nur bei MAX-Kontakten
`vk_user_id`	Zahl oder `null`	VK-Benutzer-ID. Bei allen Kontakten vorhanden, bei Nicht-VK-Kontakten `null`
`viber_id`	String	Viber-Benutzer-ID. Nur bei Viber-Kontakten
`created_at`	String	Wann der Kontakt entstanden ist, ISO 8601 in UTC
`unsubscribed_at`	String oder `null`	Wann sich der Kontakt vom Bot abgemeldet hat; `null` — angemeldet
`tags`	Array von Strings	Tags des Kontakts
`variables`	Array von Objekten	Variablen des Kontakts

Jede Variable in variables ist ein Objekt:

Feld	Beschreibung
`id`	ID der Variable beim Kontakt
`name`	Name der Variable
`value`	Wert
`type`	Was der Wert enthält: `0` — Text, `1` — Bild, `2` — Dokument, `3` — Audio, `4` — Video. Bei Medien steht in `value` ein Link zur Datei — die Methode decodeShortLink löst ihn auf
`schema_id`, `deletable`, `payload`	Interne Felder

Mehr zu Tags und Variablen im Dashboard unter Tags und Variablen.

getContacts

Liefert die Kontakte Ihrer Bots — seitenweise (standardmäßig 20 pro Seite) oder mit Versatz vom Anfang.

GETPOSThttps://watbot.org/de/api/v1/getContacts

Parameter	Typ	Pflicht	Beschreibung
`bot_id`	Zahl	nein	Nur Kontakte dieses Bots. Ohne den Parameter — Kontakte aller Ihrer Bots
`count`	Zahl	nein	Kontakte pro Seite: 1 bis 500. Standard 20
`page`	Zahl	nein	Seitennummer, ab 1. Standard 1
`offset`	Zahl	nein	Wie viele Kontakte vom Anfang übersprungen werden, ab 0. Schaltet auf Abruf mit Versatz um
`limit`	Zahl	nein	Wie viele Kontakte beim Abruf mit Versatz zurückgegeben werden: 1 bis 1000. Standard 100. Schaltet ebenfalls auf Abruf mit Versatz um
`date_from`	Zahl	nein	Kontakte, die frühestens zu diesem Zeitpunkt entstanden sind. Unix-Zeit in Sekunden
`date_to`	Zahl	nein	Kontakte, die spätestens zu diesem Zeitpunkt entstanden sind. Unix-Zeit in Sekunden
`with`	String	nein	Wird aus Kompatibilitätsgründen angenommen, z. B. `variables`. Ändert nichts: Tags und Variablen sind immer in der Antwort

Die Kontakte sind aufsteigend nach id sortiert — seitenweise wie mit Versatz. Wird offset oder limit übergeben, gilt der Versatz, und page und count werden ignoriert.

Seitenweise

Anfrage

curl -X POST "https://watbot.org/de/api/v1/getContacts" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 12345, "count": 2, "date_from": 1758931200}'

Antwort 200

{
  "data": [
    {
      "id": 4815162,
      "bot_id": 12345,
      "phone": "490001234567",
      "email": null,
      "name": "Anna Schmidt",
      "address": null,
      "messenger": "telegram",
      "utm": {"utm_source": "newsletter"},
      "avatar": null,
      "telegram_id": "123456789",
      "telegram_username": "anna_schmidt",
      "vk_user_id": null,
      "created_at": "2026-09-28T07:41:12+00:00",
      "unsubscribed_at": null,
      "tags": ["bestellt"],
      "variables": [
        {"id": 17590475010001, "name": "utm_source", "value": "newsletter", "type": 0, "schema_id": null, "deletable": false, "payload": null},
        {"id": 17590475820003, "name": "stadt", "value": "Leipzig", "type": 0, "schema_id": null, "deletable": false, "payload": null}
      ]
    },
    {
      "id": 4815170,
      "bot_id": 12345,
      "phone": null,
      "email": null,
      "name": "Lukas Müller",
      "address": null,
      "messenger": "vk",
      "utm": [],
      "avatar": null,
      "vk_user_id": 700123456,
      "created_at": "2026-09-29T15:02:47+00:00",
      "unsubscribed_at": null,
      "tags": [],
      "variables": []
    }
  ],
  "links": {
    "first": "https://watbot.org/de/api/v1/getContacts?page=1",
    "last": "https://watbot.org/de/api/v1/getContacts?page=38",
    "prev": null,
    "next": "https://watbot.org/de/api/v1/getContacts?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 38,
    "links": […],
    "path": "https://watbot.org/de/api/v1/getContacts",
    "per_page": 2,
    "to": 2,
    "total": 75
  }
}

meta.total ist die Gesamtzahl passender Kontakte, meta.last_page die Nummer der letzten Seite. Um alles zu exportieren, fragen Sie Seiten ab, bis links.next null ist. Die URLs in links enthalten außer page keinen Ihrer Parameter — senden Sie bot_id, count und die Daten bei jeder Anfrage erneut mit.
Neue Kontakte kommen ans Ende der Ausgabe: Die Sortierung nach id verhindert, dass sich Seiten verschieben. Damit die Ausgabe beim Durchblättern nicht wächst, begrenzen Sie sie mit date_to.
Eine bot_id eines fremden oder nicht existierenden Bots führt zu keinem Fehler: Die Liste ist einfach leer.

Mit Versatz

Abfrage des zweiten Hunderts Kontakte eines Bots:

Anfrage

curl -X POST "https://watbot.org/de/api/v1/getContacts" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 12345, "limit": 100, "offset": 100}'

Antwort 200

{
  "data": [
    {
      "id": 4815162,
      "bot_id": 12345,
      "phone": "490001234567",
      "email": null,
      "name": "Anna Schmidt",
      "address": null,
      "messenger": "telegram",
      "utm": [],
      "avatar": null,
      "telegram_id": "123456789",
      "telegram_username": "anna_schmidt",
      "vk_user_id": null,
      "created_at": "2026-09-28T07:41:12+00:00",
      "unsubscribed_at": null,
      "tags": ["bestellt"],
      "variables": [
        {"id": 17590475820003, "name": "stadt", "value": "Leipzig", "type": 0, "schema_id": null, "deletable": false, "payload": null}
      ]
    }
  ],
  "meta": {
    "offset": 100,
    "limit": 100,
    "total": 101
  }
}

meta.total ist die Gesamtzahl der passenden Kontakte. Der Abruf ist abgeschlossen, wenn data weniger Kontakte als limit enthält oder offset + limit meta.total erreicht hat.
Für den ersten Abschnitt übergeben Sie offset 0 oder lassen offset weg.

getNumberOfContacts

Zählt die Kontakte Ihrer Bots — mit denselben Filtern wie getContacts.

GETPOSThttps://watbot.org/de/api/v1/getNumberOfContacts

Parameter	Typ	Pflicht	Beschreibung
`bot_id`	Zahl	nein	Nur Kontakte dieses Bots. Ohne den Parameter — aller Ihrer Bots
`date_from`	Zahl	nein	Kontakte, die frühestens zu diesem Zeitpunkt entstanden sind. Unix-Zeit in Sekunden
`date_to`	Zahl	nein	Kontakte, die spätestens zu diesem Zeitpunkt entstanden sind. Unix-Zeit in Sekunden

Anfrage

curl "https://watbot.org/de/api/v1/getNumberOfContacts?bot_id=12345" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json"

Antwort 200

{
  "count": 1284
}

Die Zahl steht im Feld count auf oberster Ebene, ohne data-Hülle.

createOrUpdateContact

Legt einen Kontakt im Bot an oder aktualisiert einen vorhandenen. Der Kontakt wird im Bot über seine Messenger-ID gesucht: telegram_id, max_id, vk_id oder viber_id. Wird er gefunden, werden seine Daten aktualisiert, sonst wird ein neuer angelegt.

GETPOSThttps://watbot.org/de/api/v1/createOrUpdateContact

Parameter	Typ	Pflicht	Beschreibung
`bot_id`	Zahl	ja	ID Ihres Bots
`messenger`	String	ja	Messenger des Kontakts: `telegram`, `max`, `viber` oder `vk`
`name`	String	ja	Name des Kontakts. Ersetzt bei jedem Aufruf den bisherigen
`telegram_id`	Zahl	bei `telegram`	Telegram-Benutzer-ID
`telegram_username`	String	nein	Telegram-Benutzername, bis 255 Zeichen
`max_id`	Zahl	bei `max`	MAX-Benutzer-ID. Kann auch als `max_user_id` übergeben werden — unter diesem Namen steht sie in der Antwort
`max_username`	String	nein	MAX-Benutzername, bis 255 Zeichen
`vk_id`	Zahl	bei `vk`	VK-Benutzer-ID. Kann auch als `vk_user_id` übergeben werden — unter diesem Namen steht sie in der Antwort
`viber_id`	String	bei `viber`	Viber-Benutzer-ID, bis 255 Zeichen
`phone`	String	nein	Telefonnummer im internationalen Format: `+` und Ziffern, 9 bis 16 Zeichen einschließlich Plus — `+490001234567`. Wird als Ziffern ohne `+` gespeichert; `null` wirkt, als wäre keine Telefonnummer übergeben
`email`	String	nein	E-Mail
`address`	String	nein	Adresse, bis 255 Zeichen
`tags`	Array von Strings	nein	Tags, bis zu 100, jeweils bis 255 Zeichen. Sie ersetzen alle Tags des Kontakts

Anfrage

curl -X POST "https://watbot.org/de/api/v1/createOrUpdateContact" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": 12345,
    "messenger": "telegram",
    "telegram_id": 123456789,
    "telegram_username": "anna_schmidt",
    "name": "Anna Schmidt",
    "phone": "+490001234567",
    "email": "anna@example.com",
    "tags": ["Kunde", "aus CRM"]
  }'

Antwort 201

{
  "data": {
    "id": 4815162,
    "bot_id": 12345,
    "phone": "490001234567",
    "email": "anna@example.com",
    "name": "Anna Schmidt",
    "address": null,
    "messenger": "telegram",
    "utm": [],
    "avatar": null,
    "telegram_id": "123456789",
    "telegram_username": "anna_schmidt",
    "vk_user_id": null,
    "created_at": "2026-10-03T09:15:42+00:00",
    "unsubscribed_at": null,
    "tags": ["Kunde", "aus CRM"],
    "variables": []
  }
}

Antwort 404

{
  "message": "Bot nicht gefunden",
  "errors": {
    "bot_id": ["Bot nicht gefunden"]
  }
}

Statuscode 201 bedeutet, dass der Kontakt angelegt wurde, 200, dass ein vorhandener aktualisiert wurde.

Was sich bei einem gefundenen Kontakt ändert. name — immer. email, address, phone, telegram_username, max_username — nur, wenn sie übergeben werden und nicht leer sind: Leeren können Sie sie mit dieser Methode nicht. tags — wenn übergeben, ersetzen sie alle Tags; ein leeres Array [] entfernt alle Tags. Die Variablen des Kontakts bleiben unberührt.
Ein neuer Kontakt erscheint in der Kontaktliste des Bots mit der ersten Nachricht „Created from API“ und erhöht die Zahl der Abonnenten des Bots. Das Szenario des Bots startet dabei nicht, und dem Kontakt wird nichts gesendet.
Die Telefonnummer wird als Ziffern ohne + gespeichert — so, wie sie auch Bot-Blöcke speichern. Auch phone in der Antwort kommt ohne +.

Fehler der Methode (allgemeine unter Fehler):

Code	Wann	Antwort
`404`	Unter Ihren Bots gibt es keinen mit dieser `bot_id` — es gibt ihn nicht oder er gehört zu einem anderen Konto	`{"message": "…", "errors": {"bot_id": ["…"]}}`
`422`	Die ID für den gewählten Messenger fehlt, oder Telefonnummer bzw. E-Mail haben ein falsches Format	`{"message": "…", "errors": {…}}`

Kontakte#

Kontaktfelder#

getContacts#

Seitenweise#

Mit Versatz#

getNumberOfContacts#

createOrUpdateContact#

Kontakte

Kontaktfelder

getContacts

Seitenweise

Mit Versatz

getNumberOfContacts

createOrUpdateContact