# Теги

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

Тег — це просто рядок: створювати його заздалегідь не потрібно. Регістр має значення: «VIP» і «vip» — різні теги.

## getBotTags

Повертає довідник бота «Підказки за тегами» — імена тегів, які вводили в кабінеті.

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

| Параметр | Тип | Обов'язковий | Опис |
|---|---|---|---|
| `bot_id` | ціле число | так | Номер бота |

```bash title="Запит"
curl -X POST "https://watbot.org/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.org/api/v1/getContactTags
```

| Параметр | Тип | Обов'язковий | Опис |
|---|---|---|---|
| `contact_id` | ціле число | так | Номер контакту |

```bash title="Запит"
curl -X POST "https://watbot.org/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.org/api/v1/attachTagToContact
```

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

```bash title="Запит"
curl -X POST "https://watbot.org/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.org/api/v1/detachTagFromContact
```

| Параметр | Тип | Обов'язковий | Опис |
|---|---|---|---|
| `contact_id` | ціле число | так | Номер контакту |
| `name` | рядок | так | Ім'я тегу, до 255 символів — так можна зняти й довгий тег, поставлений блоком сценарію |

```bash title="Запит"
curl -X POST "https://watbot.org/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.org/uk/api#помилки).