# Змінні контакту

Ці методи читають, записують і видаляють [змінні контакту](https://support.watbot.org/uk/chatbots/contacts/tags-variables#змінні-контакту) — ті самі, які бот заповнює в сценарії та показує в картці контакту. Наприклад, сайт може записати в змінну номер замовлення, а бот — підставити його в повідомлення як `{{ $номер_замовлення }}` (докладніше — у розділі [Автопідстановки](https://support.watbot.org/uk/chatbots/templates)).

Номер контакту (`contact_id`) показано в шапці [картки контакту](https://support.watbot.org/uk/chatbots/contacts/card) і в першій колонці списку контактів.

## getContactVariables

Повертає всі змінні контакту.

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

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

```bash title="Запит"
curl -X POST "https://watbot.org/api/v1/getContactVariables" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 678}'
```
```json title="Відповідь 200"
{
  "data": [
    {
      "id": 17594321098765,
      "name": "місто",
      "value": "Львів",
      "deletable": false,
      "variable": {
        "id": 17594321098765,
        "name": "Львів"
      }
    },
    {
      "id": 17594321112233,
      "name": "номер_замовлення",
      "value": "A-1024",
      "deletable": false,
      "variable": {
        "id": 17594321112233,
        "name": "A-1024"
      }
    }
  ]
}
```

| Поле | Опис |
|---|---|
| `id` | Номер змінної в цього контакту |
| `name` | Ім'я змінної |
| `value` | Значення |
| `deletable` | `true` — змінна видалиться після надсилання блоку [«Заявка»](https://support.watbot.org/uk/chatbots/blocks/notifications/notification) |
| `variable` | Застаріле поле для старих інтеграцій: `id` — номер змінної, `name` — її **значення**. У новому коді не використовуйте |

Змінні йдуть у порядку створення. Якщо змінних немає, `data` буде порожнім масивом.

## setContactVariable

Записує значення в змінну контакту. Якщо змінної з таким ім'ям немає — створює її, якщо є — замінює значення.

```endpoint
POST https://watbot.org/api/v1/setContactVariable
```

| Параметр | Тип | Обов'язковий | Опис |
|---|---|---|---|
| `contact_id` | ціле число | так | Номер контакту |
| `name` | рядок | так | Ім'я змінної, до 255 символів: літери, цифри, `_` і пробіли |
| `value` | рядок | так | Значення, до 4096 символів. Число передавайте рядком: `"150"`, а не `150` |
| `deletable` | `0` або `1` | ні | `1` — видалити змінну після надсилання блоку «Заявка». Типово `0` |

```bash title="Запит"
curl -X POST "https://watbot.org/api/v1/setContactVariable" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 678, "name": "номер_замовлення", "value": "A-1024"}'
```
```json title="Відповідь 200"
{
  "data": {
    "id": 17594321112233,
    "name": "номер_замовлення",
    "value": "A-1024",
    "deletable": false,
    "variable": {
      "id": 17594321112233,
      "name": "A-1024"
    }
  }
}
```
```json title="Відповідь 422"
{
  "message": "У контакту вже 5000 змінних — нову додати не можна.",
  "error": "У контакту вже 5000 змінних — нову додати не можна.",
  "code": "variables_limit",
  "errors": {
    "name": ["У контакту вже 5000 змінних — нову додати не можна."]
  }
}
```

Особливості:

- Порожнє значення записати не можна: `value` обов'язковий. Щоб очистити змінну, видаліть її методом `deleteContactVariable`.
- Під час запису в наявну змінну `deletable` теж перезаписується: якщо параметр не передано, він стане `false`.
- Ім'я нової змінної додається до довідника бота «Підказки за змінними користувача» — так воно потрапить до підказок у кабінеті та до [вивантаження контактів](https://support.watbot.org/uk/chatbots/contacts/import-export). Якщо в довіднику вже 5000 імен, нове ім'я до нього не додається, але змінна контакту однаково записується.
- У контакту може бути не більше 5000 змінних. Нову понад це метод не створює й відповідає `422` з `code: "variables_limit"`. Запис у наявну змінну проходить завжди.
- Контакт не знайдено, його видалено або видалено його бота — `404`; контакт із чужого бота — `403`.

## deleteContactVariable

Видаляє змінну контакту за номером або за ім'ям.

```endpoint
POST https://watbot.org/api/v1/deleteContactVariable
```

| Параметр | Тип | Обов'язковий | Опис |
|---|---|---|---|
| `contact_id` | ціле число | так | Номер контакту |
| `id` | ціле число | якщо немає `name` | Номер змінної з `getContactVariables` |
| `name` | рядок | якщо немає `id` | Ім'я змінної, до 255 символів |

Якщо передано обидва, використовується `name`, а якщо змінної з таким ім'ям немає — `id`.

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

Відповідь — код `204` без тіла.

Особливості:

- Якщо такої змінної в контакту немає, метод однаково відповідає `204`.
- Ім'я з довідника підказок бота не видаляється.
- Контакт не знайдено, його видалено або видалено його бота — `404`; контакт із чужого бота — `403`.

Загальні помилки API — у розділі [Помилки](https://support.watbot.org/uk/api#помилки).