# Рефералы Когда человек приходит в бота по реферальной ссылке другого контакта, между ними возникает связь: пригласивший — **реферер**, приглашённый — **реферал**. Связи складываются в цепочку: приглашённые самим контактом — его первая линия, приглашённые ими — вторая и так далее. Как это устроено в кабинете — в разделе [Рефералы](https://support.watbot.ru/chatbots/contacts/accounts-referrals#рефералы). Методы этой страницы нужны, чтобы вести реферальную программу в своей системе: начислять бонусы по цепочке, строить отчёты по сети, проверять условия акции. Все три метода работают с контактом по его ID — `contact_id` — и только с контактами ваших ботов. Контакты в ответах — в том же виде, что у методов контактов: [Поля контакта](https://support.watbot.ru/api/contacts#поля-контакта). Ошибки, общие для методов страницы (остальные — в разделе [Ошибки](https://support.watbot.ru/api#ошибки)): | Код | Когда | Ответ | |---|---|---| | `404` | Контакта с таким `contact_id` нет среди контактов ваших ботов — его нет совсем или он в другом аккаунте | `{"message": "Контакт не найден", "errors": {"contact_id": ["Контакт не найден"]}}` | | `422` | `contact_id` не передан или не число, неверные `depth`, `level`, `is_flat` | `{"message": "…", "errors": {…}}` | Чужой контакт и несуществующий отвечают одинаково, чтобы по ответу нельзя было узнать, есть ли такой ID в другом аккаунте. ## getReferrers Возвращает цепочку рефереров контакта вверх: кто его пригласил, кто пригласил того и так далее. ```endpoint GET POST https://watbot.ru/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.ru/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": "70001234567", "email": null, "name": "Мария Иванова", "address": null, "messenger": "telegram", "utm": [], "avatar": null, "telegram_id": "123456789", "telegram_username": "maria_ivanova", "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": "olga_p", "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.ru/api/v1/getReferrals ``` | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | `contact_id` | число | да | ID контакта | | `filters[tag_name]` | строка или массив строк | нет | Только рефералы с этими тегами — со всеми сразу. Учитываются первые 10 тегов | | `page` | число | нет | Номер страницы, с 1. По умолчанию 1 | Запрос рефералов с тегом «оплатил»: ```bash title="Запрос" curl -X POST "https://watbot.ru/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.ru/api/v1/getReferrals?page=1", "last": "https://watbot.ru/api/v1/getReferrals?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": […], "path": "https://watbot.ru/api/v1/getReferrals", "per_page": 15, "to": 1, "total": 1 } } ``` Рефералы идут по возрастанию `id`. Размер страницы не меняется. Следующие страницы запрашивайте с параметром `page`, пока `links.next` не станет `null`; `contact_id` и фильтр передавайте в каждом запросе — в ссылках `links` их нет. ## getCountReferrals Считает рефералов контакта: всю сеть или одну линию. ```endpoint GET POST https://watbot.ru/api/v1/getCountReferrals ``` | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | `contact_id` | число | да | ID контакта | | `level` | число | нет | Номер линии, от 1: `1` — приглашённые самим контактом, `2` — приглашённые ими и так далее. Без параметра считается вся сеть | | `filters[tag_name]` | строка или массив строк | нет | Только рефералы с этими тегами — со всеми сразу. Учитываются первые 10 тегов | Сколько человек во второй линии: ```bash title="Запрос" curl "https://watbot.ru/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.ru/api/contacts#getnumberofcontacts) — в `count` на верхнем уровне, без `data`. Так сложилось исторически и не меняется, чтобы не сломать готовые интеграции.