# Реферали Коли людина приходить у бота за реферальним посиланням іншого контакту, між ними виникає зв'язок: той, хто запросив, — **реферер**, запрошений — **реферал**. Зв'язки складаються в ланцюжок: запрошені самим контактом — його перша лінія, запрошені ними — друга і так далі. Як це влаштовано в кабінеті — у розділі [Реферали](https://support.watbot.org/uk/chatbots/contacts/accounts-referrals#реферали). Методи цієї сторінки потрібні, щоб вести реферальну програму у своїй системі: нараховувати бонуси за ланцюжком, будувати звіти за мережею, перевіряти умови акції. Усі три методи працюють із контактом за його ID — `contact_id` — і лише з контактами ваших ботів. Контакти у відповідях — у тому самому вигляді, що й у методах контактів: [Поля контакту](https://support.watbot.org/uk/api/contacts#поля-контакту). Помилки, спільні для методів сторінки (решта — у розділі [Помилки](https://support.watbot.org/uk/api#помилки)): | Код | Коли | Відповідь | |---|---|---| | `404` | Контакту з таким `contact_id` немає серед контактів ваших ботів — його немає зовсім або він в іншому акаунті | `{"message": "Контакт не знайдено", "errors": {"contact_id": ["Контакт не знайдено"]}}` | | `422` | `contact_id` не передано або це не число; неправильні `depth`, `level` чи `is_flat` | `{"message": "…", "errors": {…}}` | Чужий контакт і неіснуючий отримують однакову відповідь, щоб за нею не можна було дізнатися, чи є такий ID в іншому акаунті. ## getReferrers Повертає ланцюжок реферерів контакту вгору: хто його запросив, хто запросив того і так далі. ```endpoint GET POST https://watbot.org/api/v1/getReferrers ``` | Параметр | Тип | Обов'язковий | Опис | |---|---|---|---| | `contact_id` | число | так | ID контакту | | `depth` | число | ні | На скільки рівнів угору підніматися: від 1 до 1000. За замовчуванням 10 | | `is_flat` | логічний | ні | `true` або `1` — повернути реферерів списком, `false` або `0` — вкладеними один в одного. В адресі `GET`-запиту — так само: `true`, `false`, `1` або `0`. За замовчуванням `false` | ```bash title="Запит" curl -X POST "https://watbot.org/api/v1/getReferrers" \ -H "Authorization: Bearer ВАШ_КЛЮЧ" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"contact_id": 4815170, "depth": 2}' ``` ```json title="Відповідь 200" { "data": { "id": 4815170, "bot_id": 12345, "phone": null, "email": null, "name": "Андрій Шевченко", "address": null, "messenger": "telegram", "utm": [], "avatar": null, "telegram_id": "223456781", "telegram_username": null, "vk_user_id": null, "created_at": "2026-09-29T15:02:47+00:00", "unsubscribed_at": null, "referrer": { "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, "referrer": { "id": 4814901, "bot_id": 12345, "phone": null, "email": null, "name": "Ірина Бондаренко", "address": null, "messenger": "telegram", "utm": [], "avatar": null, "telegram_id": "323456782", "telegram_username": "iryna_b", "vk_user_id": null, "created_at": "2026-09-20T11:30:05+00:00", "unsubscribed_at": null, "tags": ["партнер"], "variables": [] }, "tags": [], "variables": [] }, "tags": [], "variables": [] } } ``` У відповіді — сам контакт, а в полі `referrer` — його реферер зі своїм `referrer`, і так на глибину `depth`. Якщо реферера немає, поля `referrer` у контакту немає. З `"is_flat": true` у `data` приходить список реферерів без самого контакту, від найближчого до найдальшого. У кожного — поле `level`: `-1` — той, хто запросив контакт, `-2` — його реферер і так далі: ```json { "data": [ { "id": 4815162, "name": "Олена Коваленко", "…": "…", "tags": [], "variables": [], "level": -1 }, { "id": 4814901, "name": "Ірина Бондаренко", "…": "…", "tags": ["партнер"], "variables": [], "level": -2 } ] } ``` Поля контакту в списку ті самі, що вище, — тут вони скорочені. Немає реферерів — `{"data": []}`. ## getReferrals Повертає першу лінію контакту — тих, кого він запросив сам, — по 15 на сторінці. ```endpoint GET POST https://watbot.org/api/v1/getReferrals ``` | Параметр | Тип | Обов'язковий | Опис | |---|---|---|---| | `contact_id` | число | так | ID контакту | | `filters[tag_name]` | рядок або масив рядків | ні | Лише реферали з цими тегами — з усіма одразу. Враховуються перші 10 тегів | | `page` | число | ні | Номер сторінки, з 1. За замовчуванням 1 | Запит рефералів із тегом «оплатив»: ```bash title="Запит" curl -X POST "https://watbot.org/api/v1/getReferrals" \ -H "Authorization: Bearer ВАШ_КЛЮЧ" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"contact_id": 4815162, "filters": {"tag_name": ["оплатив"]}}' ``` ```json title="Відповідь 200" { "data": [ { "id": 4815170, "bot_id": 12345, "phone": null, "email": null, "name": "Андрій Шевченко", "address": null, "messenger": "telegram", "utm": [], "avatar": null, "telegram_id": "223456781", "telegram_username": null, "vk_user_id": null, "created_at": "2026-09-29T15:02:47+00:00", "unsubscribed_at": null, "tags": ["оплатив"], "variables": [] } ], "links": { "first": "https://watbot.org/api/v1/getReferrals?page=1", "last": "https://watbot.org/api/v1/getReferrals?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": […], "path": "https://watbot.org/api/v1/getReferrals", "per_page": 15, "to": 1, "total": 1 } } ``` Реферали йдуть за зростанням `id`. Розмір сторінки не змінюється. Наступні сторінки запитуйте з параметром `page`, доки `links.next` не стане `null`; `contact_id` і фільтр передавайте в кожному запиті — у посиланнях `links` їх немає. ## getCountReferrals Рахує рефералів контакту: усю мережу або одну лінію. ```endpoint GET POST https://watbot.org/api/v1/getCountReferrals ``` | Параметр | Тип | Обов'язковий | Опис | |---|---|---|---| | `contact_id` | число | так | ID контакту | | `level` | число | ні | Номер лінії, від 1: `1` — запрошені самим контактом, `2` — запрошені ними і так далі. Без параметра рахується вся мережа | | `filters[tag_name]` | рядок або масив рядків | ні | Лише реферали з цими тегами — з усіма одразу. Враховуються перші 10 тегів | Скільки людей у другій лінії: ```bash title="Запит" curl "https://watbot.org/api/v1/getCountReferrals?contact_id=4815162&level=2" \ -H "Authorization: Bearer ВАШ_КЛЮЧ" \ -H "Accept: application/json" ``` ```json title="Відповідь 200" { "data": { "count": 7 } } ``` Якщо контакт нікого не запрошував, `count` дорівнює `0`. Тут число — у `data.count`, а в [getNumberOfContacts](https://support.watbot.org/uk/api/contacts#getnumberofcontacts) — у `count` на верхньому рівні, без `data`. Так склалося історично й не змінюється, щоб не зламати готові інтеграції.