# 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](https://support.watbot.org/de/chatbots/contacts).

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](https://support.watbot.org/de/api/referrals) —, 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](https://support.watbot.org/de/api/links) löst ihn auf |
| `schema_id`, `deletable`, `payload` | Interne Felder |

Mehr zu Tags und Variablen im Dashboard unter [Tags und Variablen](https://support.watbot.org/de/chatbots/contacts/tags-variables).

## getContacts

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

```endpoint
GET POST https://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

```bash title="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}'
```

```json title="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:

```bash title="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}'
```

```json title="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`.

```endpoint
GET POST https://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 |

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

```json title="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.

```endpoint
GET POST https://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 |

```bash title="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"]
  }'
```

```json title="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": []
  }
}
```

```json title="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](https://support.watbot.org/de/api#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": {…}}` |