Рефералы

Когда человек приходит в бота по реферальной ссылке другого контакта, между ними возникает связь: пригласивший — реферер, приглашённый — реферал. Связи складываются в цепочку: приглашённые самим контактом — его первая линия, приглашённые ими — вторая и так далее. Как это устроено в кабинете — в разделе Рефералы.

Методы этой страницы нужны, чтобы вести реферальную программу в своей системе: начислять бонусы по цепочке, строить отчёты по сети, проверять условия акции.

Все три метода работают с контактом по его ID — contact_id — и только с контактами ваших ботов. Контакты в ответах — в том же виде, что у методов контактов: Поля контакта.

Ошибки, общие для методов страницы (остальные — в разделе Ошибки):

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

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

getReferrers

Возвращает цепочку рефереров контакта вверх: кто его пригласил, кто пригласил того и так далее.

GETPOSThttps://watbot.ru/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.ru/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": "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 — его реферер и так далее:

{
  "data": [
    {
      "id": 4815162,
      "name": "Мария Иванова",
      "…": "…",
      "tags": [],
      "variables": [],
      "level": -1
    },
    {
      "id": 4814901,
      "name": "Ольга Петрова",
      "…": "…",
      "tags": ["партнёр"],
      "variables": [],
      "level": -2
    }
  ]
}

Поля контакта в списке те же, что выше, — здесь они сокращены. Нет рефереров — {"data": []}.

getReferrals

Возвращает первую линию контакта — тех, кого он пригласил сам, — по 15 на странице.

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

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

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

Запрос

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

Ответ 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

Считает рефералов контакта: всю сеть или одну линию.

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

Параметр	Тип	Обязательный	Описание
`contact_id`	число	да	ID контакта
`level`	число	нет	Номер линии, от 1: `1` — приглашённые самим контактом, `2` — приглашённые ими и так далее. Без параметра считается вся сеть
`filters[tag_name]`	строка или массив строк	нет	Только рефералы с этими тегами — со всеми сразу. Учитываются первые 10 тегов

Сколько человек во второй линии:

Запрос

curl "https://watbot.ru/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