# Контакти

Контакт — це людина, яка пише боту в месенджері або в чаті на сайті. Методи цієї сторінки вивантажують контакти ваших ботів — наприклад, щоб перенести їх у CRM, — рахують їх і створюють контакт зі своєї системи, якщо ви вже знаєте ID людини в месенджері. Про контакти в кабінеті — у розділі [Контакти](https://support.watbot.org/uk/chatbots/contacts).

Вивантаження можна гортати двома способами: посторінково (`page` і `count`, до 500 контактів за запит) або зі зсувом від початку (`offset` і `limit`, до 1000 контактів за запит). Скільки контактів під умови, покаже `getNumberOfContacts`.

Методи повертають контакти лише ваших ботів. Контакти, що з'явилися під час перевірки бота в попередньому перегляді, у вивантаження й підрахунок не потрапляють.

## Поля контакту

Усі методи зі списком контактів — тут і на сторінці [Реферали](https://support.watbot.org/uk/api/referrals) — віддають контакт в одному вигляді.

| Поле | Тип | Опис |
|---|---|---|
| `id` | число | ID контакту |
| `bot_id` | число | ID бота |
| `phone` | рядок або `null` | Номер телефону, якщо контакт ним поділився або номер задано через API |
| `email` | рядок або `null` | Email |
| `name` | рядок | Ім'я |
| `address` | рядок або `null` | Адреса |
| `messenger` | рядок | Звідки контакт: `telegram`, `max`, `viber`, `vk` або `web` (чат на сайті) |
| `utm` | об'єкт | Змінні контакту, назва яких починається з `utm_`: `{"utm_source": "…"}`. Якщо таких немає — порожній масив `[]` |
| `avatar` | рядок або `null` | Посилання на фото контакту. Посилання на файл у сховищі тимчасове — зберігайте сам файл, а не посилання |
| `telegram_id` | рядок | ID користувача в Telegram. Лише в контактів Telegram |
| `telegram_username` | рядок або `null` | Username у Telegram без `@`. Лише в контактів Telegram |
| `max_user_id` | число | ID користувача в MAX. Лише в контактів MAX |
| `max_username` | рядок або `null` | Username у MAX. Лише в контактів MAX |
| `vk_user_id` | число або `null` | ID користувача ВКонтакте. Є в усіх контактів, у контактів не з ВКонтакте — `null` |
| `viber_id` | рядок | ID користувача у Viber. Лише в контактів Viber |
| `created_at` | рядок | Коли контакт з'явився, ISO 8601 в UTC |
| `unsubscribed_at` | рядок або `null` | Коли контакт відписався від бота; `null` — підписаний |
| `tags` | масив рядків | Теги контакту |
| `variables` | масив об'єктів | Змінні контакту |

Кожна змінна у `variables` — об'єкт:

| Поле | Опис |
|---|---|
| `id` | ID змінної в контакту |
| `name` | Назва змінної |
| `value` | Значення |
| `type` | Що в значенні: `0` — текст, `1` — зображення, `2` — документ, `3` — аудіо, `4` — відео. У медіа у `value` посилання на файл — його розкриває метод [decodeShortLink](https://support.watbot.org/uk/api/links) |
| `schema_id`, `deletable`, `payload` | Службові поля |

Про теги та змінні в кабінеті — на сторінці [Теги та змінні](https://support.watbot.org/uk/chatbots/contacts/tags-variables).

## getContacts

Повертає контакти ваших ботів — посторінково (за замовчуванням 20 на сторінці) або зі зсувом від початку.

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

| Параметр | Тип | Обов'язковий | Опис |
|---|---|---|---|
| `bot_id` | число | ні | Лише контакти цього бота. Без параметра — контакти всіх ваших ботів |
| `count` | число | ні | Контактів на сторінці: від 1 до 500. За замовчуванням 20 |
| `page` | число | ні | Номер сторінки, з 1. За замовчуванням 1 |
| `offset` | число | ні | Скільки контактів пропустити від початку, від 0. Вмикає вивантаження зі зсувом |
| `limit` | число | ні | Скільки контактів повернути при вивантаженні зі зсувом: від 1 до 1000. За замовчуванням 100. Теж вмикає вивантаження зі зсувом |
| `date_from` | число | ні | Контакти, що з'явилися не раніше цього моменту. Unix-час у секундах |
| `date_to` | число | ні | Контакти, що з'явилися не пізніше цього моменту. Unix-час у секундах |
| `with` | рядок | ні | Приймається для сумісності, наприклад `variables`. Нічого не змінює: теги й змінні є у відповіді завжди |

Контакти йдуть за зростанням `id` — і посторінково, і зі зсувом. Якщо передано `offset` або `limit`, працює зсув, а `page` і `count` не враховуються.

### Посторінково

```bash title="Запит"
curl -X POST "https://watbot.org/api/v1/getContacts" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 12345, "count": 2, "date_from": 1758931200}'
```

```json title="Відповідь 200"
{
  "data": [
    {
      "id": 4815162,
      "bot_id": 12345,
      "phone": "380001234567",
      "email": null,
      "name": "Олена Коваленко",
      "address": null,
      "messenger": "telegram",
      "utm": {"utm_source": "newsletter"},
      "avatar": null,
      "telegram_id": "123456789",
      "telegram_username": "olena_kovalenko",
      "vk_user_id": null,
      "created_at": "2026-09-28T07:41:12+00:00",
      "unsubscribed_at": null,
      "tags": ["оформив замовлення"],
      "variables": [
        {"id": 17590475010001, "name": "utm_source", "value": "newsletter", "type": 0, "schema_id": null, "deletable": false, "payload": null},
        {"id": 17590475820003, "name": "місто", "value": "Львів", "type": 0, "schema_id": null, "deletable": false, "payload": null}
      ]
    },
    {
      "id": 4815170,
      "bot_id": 12345,
      "phone": null,
      "email": null,
      "name": "Андрій Шевченко",
      "address": null,
      "messenger": "vk",
      "utm": [],
      "avatar": null,
      "vk_user_id": 700123456,
      "created_at": "2026-09-29T15:02:47+00:00",
      "unsubscribed_at": null,
      "tags": [],
      "variables": []
    }
  ],
  "links": {
    "first": "https://watbot.org/api/v1/getContacts?page=1",
    "last": "https://watbot.org/api/v1/getContacts?page=38",
    "prev": null,
    "next": "https://watbot.org/api/v1/getContacts?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 38,
    "links": […],
    "path": "https://watbot.org/api/v1/getContacts",
    "per_page": 2,
    "to": 2,
    "total": 75
  }
}
```

- `meta.total` — скільки всього контактів відповідають умовам, `meta.last_page` — номер останньої сторінки. Щоб вивантажити все, запитуйте сторінки, доки `links.next` не стане `null`. У посиланнях `links` немає ваших параметрів, крім `page`, — `bot_id`, `count` і дати передавайте в кожному запиті заново.
- Нові контакти потрапляють у кінець вивантаження — порядок за `id` не дає сторінкам зсуватися. Щоб вивантаження не росло, поки ви його гортаєте, обмежте його параметром `date_to`.
- `bot_id` чужого або неіснуючого бота не дає помилки: список буде порожнім.

### Зі зсувом

Запит другої сотні контактів бота:

```bash title="Запит"
curl -X POST "https://watbot.org/api/v1/getContacts" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 12345, "limit": 100, "offset": 100}'
```

```json title="Відповідь 200"
{
  "data": [
    {
      "id": 4815162,
      "bot_id": 12345,
      "phone": "380001234567",
      "email": null,
      "name": "Олена Коваленко",
      "address": null,
      "messenger": "telegram",
      "utm": [],
      "avatar": null,
      "telegram_id": "123456789",
      "telegram_username": "olena_kovalenko",
      "vk_user_id": null,
      "created_at": "2026-09-28T07:41:12+00:00",
      "unsubscribed_at": null,
      "tags": ["оформив замовлення"],
      "variables": [
        {"id": 17590475820003, "name": "місто", "value": "Львів", "type": 0, "schema_id": null, "deletable": false, "payload": null}
      ]
    }
  ],
  "meta": {
    "offset": 100,
    "limit": 100,
    "total": 101
  }
}
```

- `meta.total` — скільки всього контактів під умови. Вивантаження завершено, коли в `data` прийшло менше контактів, ніж `limit`, або `offset + limit` дійшов до `meta.total`.
- Перша порція — `offset` `0` або без `offset`.

## getNumberOfContacts

Рахує контакти ваших ботів — з тими самими фільтрами, що в `getContacts`.

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

| Параметр | Тип | Обов'язковий | Опис |
|---|---|---|---|
| `bot_id` | число | ні | Лише контакти цього бота. Без параметра — усіх ваших ботів |
| `date_from` | число | ні | Контакти, що з'явилися не раніше цього моменту. Unix-час у секундах |
| `date_to` | число | ні | Контакти, що з'явилися не пізніше цього моменту. Unix-час у секундах |

```bash title="Запит"
curl "https://watbot.org/api/v1/getNumberOfContacts?bot_id=12345" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json"
```

```json title="Відповідь 200"
{
  "count": 1284
}
```

Число — у полі `count` на верхньому рівні, без обгортки `data`.

## createOrUpdateContact

Створює контакт у боті або оновлює знайдений. Контакт шукається в боті за ID у месенджері: `telegram_id`, `max_id`, `vk_id` або `viber_id`. Знайшовся — його дані оновлюються, ні — створюється новий.

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

| Параметр | Тип | Обов'язковий | Опис |
|---|---|---|---|
| `bot_id` | число | так | ID вашого бота |
| `messenger` | рядок | так | Месенджер контакту: `telegram`, `max`, `viber` або `vk` |
| `name` | рядок | так | Ім'я контакту. Замінює попереднє під час кожного виклику |
| `telegram_id` | число | для `telegram` | ID користувача в Telegram |
| `telegram_username` | рядок | ні | Username у Telegram, до 255 символів |
| `max_id` | число | для `max` | ID користувача в MAX. Можна передати і як `max_user_id` — під цим іменем він приходить у відповіді |
| `max_username` | рядок | ні | Username у MAX, до 255 символів |
| `vk_id` | число | для `vk` | ID користувача ВКонтакте. Можна передати і як `vk_user_id` — під цим іменем він приходить у відповіді |
| `viber_id` | рядок | для `viber` | ID користувача у Viber, до 255 символів |
| `phone` | рядок | ні | Телефон у міжнародному форматі: `+` і цифри, від 9 до 16 символів разом із плюсом — `+380001234567`. Зберігається цифрами, без `+`; `null` — так само, як якби телефон не передали |
| `email` | рядок | ні | Email |
| `address` | рядок | ні | Адреса, до 255 символів |
| `tags` | масив рядків | ні | Теги, до 100 штук, кожен до 255 символів. **Замінюють** усі теги контакту |

```bash title="Запит"
curl -X POST "https://watbot.org/api/v1/createOrUpdateContact" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": 12345,
    "messenger": "telegram",
    "telegram_id": 123456789,
    "telegram_username": "olena_kovalenko",
    "name": "Олена Коваленко",
    "phone": "+380001234567",
    "email": "olena@example.com",
    "tags": ["клієнт", "з CRM"]
  }'
```

```json title="Відповідь 201"
{
  "data": {
    "id": 4815162,
    "bot_id": 12345,
    "phone": "380001234567",
    "email": "olena@example.com",
    "name": "Олена Коваленко",
    "address": null,
    "messenger": "telegram",
    "utm": [],
    "avatar": null,
    "telegram_id": "123456789",
    "telegram_username": "olena_kovalenko",
    "vk_user_id": null,
    "created_at": "2026-10-03T09:15:42+00:00",
    "unsubscribed_at": null,
    "tags": ["клієнт", "з CRM"],
    "variables": []
  }
}
```

```json title="Відповідь 404"
{
  "message": "Бота не знайдено",
  "errors": {
    "bot_id": ["Бота не знайдено"]
  }
}
```

Код відповіді `201` — контакт створено, `200` — оновлено наявний.

- **Що змінюється в знайденого контакту.** `name` — завжди. `email`, `address`, `phone`, `telegram_username`, `max_username` — лише якщо передані й не порожні: очистити їх цим методом не можна. `tags` — якщо передані, замінюють увесь набір тегів; порожній масив `[]` знімає всі теги. Змінних контакту метод не торкається.
- **Новий контакт** з'являється у списку контактів бота з першим повідомленням «Created from API» і збільшує кількість підписників бота. Сценарій бота при цьому не запускається, і контакту нічого не надсилається.
- **Телефон** зберігається цифрами, без `+`, — так само, як його зберігають блоки бота. У відповіді `phone` теж без `+`.

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

| Код | Коли | Відповідь |
|---|---|---|
| `404` | Бота з таким `bot_id` немає серед ваших — його немає зовсім або він в іншому акаунті | `{"message": "…", "errors": {"bot_id": ["…"]}}` |
| `422` | Не передано ID для вибраного месенджера, неправильний формат телефону або email | `{"message": "…", "errors": {…}}` |