Реферали

Коли людина приходить у бота за реферальним посиланням іншого контакту, між ними виникає зв'язок: той, хто запросив, — реферер, запрошений — реферал. Зв'язки складаються в ланцюжок: запрошені самим контактом — його перша лінія, запрошені ними — друга і так далі. Як це влаштовано в кабінеті — у розділі Реферали.

Методи цієї сторінки потрібні, щоб вести реферальну програму у своїй системі: нараховувати бонуси за ланцюжком, будувати звіти за мережею, перевіряти умови акції.

Усі три методи працюють із контактом за його ID — contact_id — і лише з контактами ваших ботів. Контакти у відповідях — у тому самому вигляді, що й у методах контактів: Поля контакту.

Помилки, спільні для методів сторінки (решта — у розділі Помилки):

Код	Коли	Відповідь
`404`	Контакту з таким `contact_id` немає серед контактів ваших ботів — його немає зовсім або він в іншому акаунті	`{"message": "Контакт не знайдено", "errors": {"contact_id": ["Контакт не знайдено"]}}`
`422`	`contact_id` не передано або це не число; неправильні `depth`, `level` чи `is_flat`	`{"message": "…", "errors": {…}}`

Чужий контакт і неіснуючий отримують однакову відповідь, щоб за нею не можна було дізнатися, чи є такий ID в іншому акаунті.

getReferrers

Повертає ланцюжок реферерів контакту вгору: хто його запросив, хто запросив того і так далі.

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

Параметр	Тип	Обов'язковий	Опис
`contact_id`	число	так	ID контакту
`depth`	число	ні	На скільки рівнів угору підніматися: від 1 до 1000. За замовчуванням 10
`is_flat`	логічний	ні	`true` або `1` — повернути реферерів списком, `false` або `0` — вкладеними один в одного. В адресі `GET`-запиту — так само: `true`, `false`, `1` або `0`. За замовчуванням `false`

Запит

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

Відповідь 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 — його реферер і так далі:

{
  "data": [
    {
      "id": 4815162,
      "name": "Олена Коваленко",
      "…": "…",
      "tags": [],
      "variables": [],
      "level": -1
    },
    {
      "id": 4814901,
      "name": "Ірина Бондаренко",
      "…": "…",
      "tags": ["партнер"],
      "variables": [],
      "level": -2
    }
  ]
}

Поля контакту в списку ті самі, що вище, — тут вони скорочені. Немає реферерів — {"data": []}.

getReferrals

Повертає першу лінію контакту — тих, кого він запросив сам, — по 15 на сторінці.

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

Параметр	Тип	Обов'язковий	Опис
`contact_id`	число	так	ID контакту
`filters[tag_name]`	рядок або масив рядків	ні	Лише реферали з цими тегами — з усіма одразу. Враховуються перші 10 тегів
`page`	число	ні	Номер сторінки, з 1. За замовчуванням 1

Запит рефералів із тегом «оплатив»:

Запит

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": ["оплатив"]}}'

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

Рахує рефералів контакту: усю мережу або одну лінію.

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

Параметр	Тип	Обов'язковий	Опис
`contact_id`	число	так	ID контакту
`level`	число	ні	Номер лінії, від 1: `1` — запрошені самим контактом, `2` — запрошені ними і так далі. Без параметра рахується вся мережа
`filters[tag_name]`	рядок або масив рядків	ні	Лише реферали з цими тегами — з усіма одразу. Враховуються перші 10 тегів

Скільки людей у другій лінії:

Запит

curl "https://watbot.org/api/v1/getCountReferrals?contact_id=4815162&level=2" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json"

Відповідь 200

{
  "data": {
    "count": 7
  }
}

Якщо контакт нікого не запрошував, count дорівнює 0.

Тут число — у data.count, а в getNumberOfContacts — у count на верхньому рівні, без data. Так склалося історично й не змінюється, щоб не зламати готові інтеграції.

Реферали#

getReferrers#

getReferrals#

getCountReferrals#

Реферали

getReferrers

getReferrals

getCountReferrals