# Переменные контакта

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

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

## getContactVariables

Возвращает все переменные контакта.

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

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

```bash title="Запрос"
curl -X POST "https://watbot.ru/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.ru/chatbots/blocks/notifications/notification) |
| `variable` | Устаревшее поле для старых интеграций: `id` — номер переменной, `name` — её **значение**. В новом коде не используйте |

Переменные идут в порядке создания. Нет переменных — `data` будет пустым массивом.

## setContactVariable

Записывает значение в переменную контакта. Если переменной с таким именем нет — создаёт её, если есть — заменяет значение.

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

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

```bash title="Запрос"
curl -X POST "https://watbot.ru/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.ru/chatbots/contacts/import-export). Если в справочнике уже 5000 имён, новое имя в него не добавляется, но переменная контакта всё равно записывается.
- У контакта может быть не больше 5000 переменных. Новую сверх этого метод не создаёт и отвечает `422` с `code: "variables_limit"`. Запись в существующую переменную проходит всегда.
- Нет контакта, он удалён или удалён его бот — `404`; контакт из чужого бота — `403`.

## deleteContactVariable

Удаляет переменную контакта по номеру или по имени.

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

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

Если переданы оба, используется `name`, а если переменной с таким именем нет — `id`.

```bash title="Запрос"
curl -X POST "https://watbot.ru/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.ru/api#ошибки).