# Теги

Эти методы показывают [теги](https://support.watbot.ru/chatbots/contacts/tags-variables#теги) бота и контакта, назначают и снимают их. Например, после оплаты на сайте можно поставить контакту тег «оплатил», а в сценарии проверить его блоком [«Условие»](https://support.watbot.ru/chatbots/blocks/logic/condition) или отобрать по нему получателей рассылки.

Тег — просто строка: заранее создавать его не нужно. Регистр важен: «VIP» и «vip» — разные теги.

## getBotTags

Возвращает справочник «Подсказки по тегам» бота — имена тегов, которые вводили в кабинете.

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

| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| `bot_id` | целое | да | Номер бота |

```bash title="Запрос"
curl -X POST "https://watbot.ru/api/v1/getBotTags" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 12345}'
```
```json title="Ответ 200"
{
  "data": ["vip", "оплатил", "новичок"]
}
```

Особенности:

- Справочник — не полный список тегов контактов. В него попадают имена, введённые в кабинете, и новые теги, поставленные методом `attachTagToContact` (пока в справочнике меньше 5000 имён). Теги, которые ставят блоки сценария, сами в него не добавляются, а удаление имени из справочника не снимает тег с контактов.
- Нет бота или он удалён — `404`; чужой бот — `403`.

## getContactTags

Возвращает теги контакта.

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

| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| `contact_id` | целое | да | Номер контакта |

```bash title="Запрос"
curl -X POST "https://watbot.ru/api/v1/getContactTags" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 678}'
```
```json title="Ответ 200"
{
  "data": ["vip", "оплатил"]
}
```

Нет тегов — `data` будет пустым массивом. Нет контакта, он удалён или удалён его бот — `404`; контакт из чужого бота — `403`.

## attachTagToContact

Назначает контакту тег.

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

| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| `contact_id` | целое | да | Номер контакта |
| `name` | строка | да | Имя тега, до 60 символов (как в кабинете): буквы, цифры, пробелы, `_`, `.` и `-` |

```bash title="Запрос"
curl -X POST "https://watbot.ru/api/v1/attachTagToContact" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 678, "name": "оплатил"}'
```
```json title="Ответ 422"
{
  "message": "У контакта уже 1000 тегов — больше добавить нельзя.",
  "error": "У контакта уже 1000 тегов — больше добавить нельзя.",
  "code": "tags_limit",
  "errors": {
    "name": ["У контакта уже 1000 тегов — больше добавить нельзя."]
  }
}
```

Ответ — код `204` без тела.

Особенности:

- Если тег у контакта уже есть, второй раз он не добавится — ответ тот же, `204`.
- У контакта может быть не больше 1000 тегов. Новый тег сверх этого метод не ставит и отвечает `422` с `code: "tags_limit"`.
- Новый тег попадает и в справочник подсказок бота — его вернёт `getBotTags`.
- Нет контакта, он удалён или удалён его бот — `404`; контакт из чужого бота — `403`.

## detachTagFromContact

Снимает тег с контакта.

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

| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| `contact_id` | целое | да | Номер контакта |
| `name` | строка | да | Имя тега, до 255 символов — так можно снять и длинный тег, поставленный блоком сценария |

```bash title="Запрос"
curl -X POST "https://watbot.ru/api/v1/detachTagFromContact" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 678, "name": "оплатил"}'
```

Ответ — код `204` без тела. Если такого тега у контакта не было, ответ тот же.

Нет контакта, он удалён или удалён его бот — `404`; контакт из чужого бота — `403`.

Общие ошибки API — в разделе [Ошибки](https://support.watbot.ru/api#ошибки).