# Tags

Mit diesen Methoden zeigen Sie die [Tags](https://support.watbot.org/de/chatbots/contacts/tags-variables#tags) eines Bots und eines Kontakts an, weisen sie zu und entfernen sie. Zum Beispiel können Sie dem Kontakt nach einer Zahlung auf Ihrer Website den Tag „bezahlt“ geben, ihn im Szenario mit dem Block [„Bedingung“](https://support.watbot.org/de/chatbots/blocks/logic/condition) prüfen oder danach die Empfänger eines Mailings auswählen.

Ein Tag ist einfach eine Zeichenkette: Sie müssen ihn nicht vorab anlegen. Groß- und Kleinschreibung zählen: „VIP“ und „vip“ sind verschiedene Tags.

## getBotTags

Gibt das Verzeichnis „Tag-Vorschläge“ des Bots zurück — die Namen der Tags, die in der Oberfläche eingegeben wurden.

```endpoint
GET POST https://watbot.org/de/api/v1/getBotTags
```

| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `bot_id` | Ganzzahl | ja | ID des Bots |

```bash title="Anfrage"
curl -X POST "https://watbot.org/de/api/v1/getBotTags" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 12345}'
```
```json title="Antwort 200"
{
  "data": ["vip", "bezahlt", "neukunde"]
}
```

Besonderheiten:

- Das Verzeichnis ist keine vollständige Liste der Tags von Kontakten. Es enthält die in der Oberfläche eingegebenen Namen und neue Tags, die mit `attachTagToContact` gesetzt werden (solange das Verzeichnis weniger als 5000 Namen hat). Tags, die Blöcke im Szenario setzen, kommen nicht von selbst hinein, und wenn Sie einen Namen aus dem Verzeichnis entfernen, bleibt der Tag bei den Kontakten.
- Bot nicht gefunden oder gelöscht — `404`; fremder Bot — `403`.

## getContactTags

Gibt die Tags eines Kontakts zurück.

```endpoint
GET POST https://watbot.org/de/api/v1/getContactTags
```

| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `contact_id` | Ganzzahl | ja | ID des Kontakts |

```bash title="Anfrage"
curl -X POST "https://watbot.org/de/api/v1/getContactTags" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 678}'
```
```json title="Antwort 200"
{
  "data": ["vip", "bezahlt"]
}
```

Hat der Kontakt keine Tags, ist `data` ein leeres Array. Kontakt nicht gefunden, gelöscht oder sein Bot gelöscht — `404`; Kontakt aus einem fremden Bot — `403`.

## attachTagToContact

Weist einem Kontakt einen Tag zu.

```endpoint
GET POST https://watbot.org/de/api/v1/attachTagToContact
```

| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `contact_id` | Ganzzahl | ja | ID des Kontakts |
| `name` | Zeichenkette | ja | Name des Tags, bis 60 Zeichen (wie in der Oberfläche): Buchstaben, Ziffern, Leerzeichen, `_`, `.` und `-` |

```bash title="Anfrage"
curl -X POST "https://watbot.org/de/api/v1/attachTagToContact" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 678, "name": "bezahlt"}'
```
```json title="Antwort 422"
{
  "message": "Der Kontakt hat bereits 1000 Tags — weitere können nicht hinzugefügt werden.",
  "error": "Der Kontakt hat bereits 1000 Tags — weitere können nicht hinzugefügt werden.",
  "code": "tags_limit",
  "errors": {
    "name": ["Der Kontakt hat bereits 1000 Tags — weitere können nicht hinzugefügt werden."]
  }
}
```

Die Antwort ist der Status `204` ohne Inhalt.

Besonderheiten:

- Hat der Kontakt den Tag schon, wird er kein zweites Mal hinzugefügt — die Antwort ist ebenfalls `204`.
- Ein Kontakt kann höchstens 1000 Tags haben. Darüber hinaus setzt die Methode keinen neuen Tag und antwortet mit `422` und `code: "tags_limit"`.
- Ein neuer Tag kommt auch in das Vorschlagsverzeichnis des Bots — `getBotTags` gibt ihn zurück.
- Kontakt nicht gefunden, gelöscht oder sein Bot gelöscht — `404`; Kontakt aus einem fremden Bot — `403`.

## detachTagFromContact

Entfernt einen Tag von einem Kontakt.

```endpoint
GET POST https://watbot.org/de/api/v1/detachTagFromContact
```

| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `contact_id` | Ganzzahl | ja | ID des Kontakts |
| `name` | Zeichenkette | ja | Name des Tags, bis 255 Zeichen — so lässt sich auch ein langer Tag entfernen, den ein Block im Szenario gesetzt hat |

```bash title="Anfrage"
curl -X POST "https://watbot.org/de/api/v1/detachTagFromContact" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 678, "name": "bezahlt"}'
```

Die Antwort ist der Status `204` ohne Inhalt. Hatte der Kontakt diesen Tag nicht, ist die Antwort dieselbe.

Kontakt nicht gefunden, gelöscht oder sein Bot gelöscht — `404`; Kontakt aus einem fremden Bot — `403`.

Allgemeine Fehler der API finden Sie unter [Fehler](https://support.watbot.org/de/api#fehler).