Контакти

Контакт — це людина, яка пише боту в месенджері або в чаті на сайті. Методи цієї сторінки вивантажують контакти ваших ботів — наприклад, щоб перенести їх у CRM, — рахують їх і створюють контакт зі своєї системи, якщо ви вже знаєте ID людини в месенджері. Про контакти в кабінеті — у розділі Контакти.

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

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

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

Усі методи зі списком контактів — тут і на сторінці Реферали — віддають контакт в одному вигляді.

Поле	Тип	Опис
`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
`schema_id`, `deletable`, `payload`	Службові поля

Про теги та змінні в кабінеті — на сторінці Теги та змінні.

getContacts

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

GETPOSThttps://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 не враховуються.

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

Запит

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}'

Відповідь 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 чужого або неіснуючого бота не дає помилки: список буде порожнім.

Зі зсувом

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

Запит

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}'

Відповідь 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.

GETPOSThttps://watbot.org/api/v1/getNumberOfContacts

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

Запит

curl "https://watbot.org/api/v1/getNumberOfContacts?bot_id=12345" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json"

Відповідь 200

{
  "count": 1284
}

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

createOrUpdateContact

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

GETPOSThttps://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 символів. Замінюють усі теги контакту

Запит

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"]
  }'

Відповідь 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": []
  }
}

Відповідь 404

{
  "message": "Бота не знайдено",
  "errors": {
    "bot_id": ["Бота не знайдено"]
  }
}

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

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

Помилки методу (загальні — у розділі Помилки):

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

Контакти#

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

getContacts#

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

Зі зсувом#

getNumberOfContacts#

createOrUpdateContact#

Контакти

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

getContacts

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

Зі зсувом

getNumberOfContacts

createOrUpdateContact