# Eingeladene Kommt eine Person über den Empfehlungslink eines anderen Kontakts in den Bot, entsteht zwischen beiden eine Beziehung: Wer eingeladen hat, ist der **Referrer**, wer eingeladen wurde, der **Eingeladene**. Die Beziehungen bilden eine Kette: Die, die ein Kontakt selbst eingeladen hat, sind seine erste Ebene, die von ihnen Eingeladenen die zweite und so weiter. Wie das im Dashboard aussieht, lesen Sie unter [Eingeladene](https://support.watbot.org/de/chatbots/contacts/accounts-referrals#eingeladene). Mit den Methoden auf dieser Seite führen Sie ein Empfehlungsprogramm in Ihrem eigenen System: Boni entlang der Kette vergeben, Netzwerkberichte erstellen, Aktionsbedingungen prüfen. Alle drei Methoden erwarten einen Kontakt über seine ID — `contact_id` — und arbeiten nur mit Kontakten Ihrer eigenen Bots. Kontakte in den Antworten haben dieselbe Form wie bei den Kontaktmethoden: [Kontaktfelder](https://support.watbot.org/de/api/contacts#kontaktfelder). Fehler, die für alle Methoden dieser Seite gelten (weitere unter [Fehler](https://support.watbot.org/de/api#fehler)): | Code | Wann | Antwort | |---|---|---| | `404` | Unter den Kontakten Ihrer Bots gibt es keinen mit dieser `contact_id` — es gibt ihn nicht oder er gehört zu einem anderen Konto | `{"message": "Kontakt nicht gefunden", "errors": {"contact_id": ["Kontakt nicht gefunden"]}}` | | `422` | `contact_id` fehlt oder ist keine Zahl; ungültige `depth`, `level` oder `is_flat` | `{"message": "…", "errors": {…}}` | Ein Kontakt eines anderen Kontos und ein nicht existierender werden gleich beantwortet — so verrät die Antwort nicht, ob es die ID in einem anderen Konto gibt. ## getReferrers Liefert die Kette der Referrer eines Kontakts nach oben: wer ihn eingeladen hat, wer diese Person eingeladen hat und so weiter. ```endpoint GET POST https://watbot.org/de/api/v1/getReferrers ``` | Parameter | Typ | Pflicht | Beschreibung | |---|---|---|---| | `contact_id` | Zahl | ja | Kontakt-ID | | `depth` | Zahl | nein | Wie viele Ebenen nach oben: 1 bis 1000. Standard 10 | | `is_flat` | Boolean | nein | `true` oder `1` — die Referrer als Liste liefern, `false` oder `0` — ineinander verschachtelt. In der URL einer `GET`-Anfrage ebenso: `true`, `false`, `1` oder `0`. Standard `false` | ```bash title="Anfrage" curl -X POST "https://watbot.org/de/api/v1/getReferrers" \ -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"contact_id": 4815170, "depth": 2}' ``` ```json title="Antwort 200" { "data": { "id": 4815170, "bot_id": 12345, "phone": null, "email": null, "name": "Lukas Müller", "address": null, "messenger": "telegram", "utm": [], "avatar": null, "telegram_id": "223456781", "telegram_username": null, "vk_user_id": null, "created_at": "2026-09-29T15:02:47+00:00", "unsubscribed_at": null, "referrer": { "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, "referrer": { "id": 4814901, "bot_id": 12345, "phone": null, "email": null, "name": "Julia Wagner", "address": null, "messenger": "telegram", "utm": [], "avatar": null, "telegram_id": "323456782", "telegram_username": "julia_w", "vk_user_id": null, "created_at": "2026-09-20T11:30:05+00:00", "unsubscribed_at": null, "tags": ["Partner"], "variables": [] }, "tags": [], "variables": [] }, "tags": [], "variables": [] } } ``` Die Antwort enthält den Kontakt selbst, im Feld `referrer` seinen Referrer mit dessen eigenem `referrer` und so weiter bis zur Tiefe `depth`. Hat der Kontakt keinen Referrer, fehlt das Feld `referrer`. Mit `"is_flat": true` enthält `data` eine Liste der Referrer ohne den Kontakt selbst, vom nächsten zum entferntesten. Jeder hat ein Feld `level`: `-1` ist die Person, die den Kontakt eingeladen hat, `-2` deren Referrer und so weiter: ```json { "data": [ { "id": 4815162, "name": "Anna Schmidt", "…": "…", "tags": [], "variables": [], "level": -1 }, { "id": 4814901, "name": "Julia Wagner", "…": "…", "tags": ["Partner"], "variables": [], "level": -2 } ] } ``` Die Kontaktfelder in der Liste sind dieselben wie oben — hier gekürzt. Keine Referrer — `{"data": []}`. ## getReferrals Liefert die erste Ebene des Kontakts — die Personen, die er selbst eingeladen hat —, 15 pro Seite. ```endpoint GET POST https://watbot.org/de/api/v1/getReferrals ``` | Parameter | Typ | Pflicht | Beschreibung | |---|---|---|---| | `contact_id` | Zahl | ja | Kontakt-ID | | `filters[tag_name]` | String oder Array von Strings | nein | Nur Eingeladene mit diesen Tags — mit allen gleichzeitig. Berücksichtigt werden die ersten 10 Tags | | `page` | Zahl | nein | Seitennummer, ab 1. Standard 1 | Abfrage der Eingeladenen mit dem Tag „bezahlt“: ```bash title="Anfrage" curl -X POST "https://watbot.org/de/api/v1/getReferrals" \ -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"contact_id": 4815162, "filters": {"tag_name": ["bezahlt"]}}' ``` ```json title="Antwort 200" { "data": [ { "id": 4815170, "bot_id": 12345, "phone": null, "email": null, "name": "Lukas Müller", "address": null, "messenger": "telegram", "utm": [], "avatar": null, "telegram_id": "223456781", "telegram_username": null, "vk_user_id": null, "created_at": "2026-09-29T15:02:47+00:00", "unsubscribed_at": null, "tags": ["bezahlt"], "variables": [] } ], "links": { "first": "https://watbot.org/de/api/v1/getReferrals?page=1", "last": "https://watbot.org/de/api/v1/getReferrals?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": […], "path": "https://watbot.org/de/api/v1/getReferrals", "per_page": 15, "to": 1, "total": 1 } } ``` Die Referrals sind aufsteigend nach `id` sortiert. Die Seitengröße ist fest. Fragen Sie weitere Seiten mit dem Parameter `page` ab, bis `links.next` `null` ist; senden Sie `contact_id` und den Filter bei jeder Anfrage mit — die URLs in `links` enthalten sie nicht. ## getCountReferrals Zählt die Eingeladenen eines Kontakts: das ganze Netzwerk oder eine einzelne Ebene. ```endpoint GET POST https://watbot.org/de/api/v1/getCountReferrals ``` | Parameter | Typ | Pflicht | Beschreibung | |---|---|---|---| | `contact_id` | Zahl | ja | Kontakt-ID | | `level` | Zahl | nein | Nummer der Ebene, ab 1: `1` — vom Kontakt selbst Eingeladene, `2` — von ihnen Eingeladene und so weiter. Ohne den Parameter wird das ganze Netzwerk gezählt | | `filters[tag_name]` | String oder Array von Strings | nein | Nur Eingeladene mit diesen Tags — mit allen gleichzeitig. Berücksichtigt werden die ersten 10 Tags | Wie viele Personen in der zweiten Ebene sind: ```bash title="Anfrage" curl "https://watbot.org/de/api/v1/getCountReferrals?contact_id=4815162&level=2" \ -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \ -H "Accept: application/json" ``` ```json title="Antwort 200" { "data": { "count": 7 } } ``` Hat der Kontakt niemanden eingeladen, ist `count` gleich `0`. Hier steht die Zahl in `data.count`, bei [getNumberOfContacts](https://support.watbot.org/de/api/contacts#getnumberofcontacts) dagegen in `count` auf oberster Ebene, ohne `data`. Das ist historisch so und bleibt, damit bestehende Integrationen nicht brechen.