Ask AI
English EN
Go to Watbot
Open as markdown The page text without formatting Open in ChatGPT Ask a question about this page Open in Claude Ask a question about this page Connect to Cursor Help center MCP server in one click Connect to VS Code Help center MCP server in one click How to connect the help center to AI

Referrals

When a person comes to a bot through another contact's referral link, a link between them is created: the one who invited is the referrer, the invited one is the referral. The links form a chain: those the contact invited personally are their first line, those invited by them are the second line, and so on. For how this works in the dashboard, see Referrals.

The methods on this page let you run a referral programme in your own system: award bonuses along the chain, build network reports, check promotion conditions.

All three methods take a contact by its ID — contact_id — and work only with contacts of your own bots. Contacts in the responses have the same shape as in the contact methods: Contact fields.

Errors common to the methods on this page (others are under Errors):

Code When Response
404 None of your bots' contacts has this contact_id — it does not exist or belongs to another account {"message": "Contact not found", "errors": {"contact_id": ["Contact not found"]}}
422 contact_id is missing or not a number; invalid depth, level or is_flat {"message": "…", "errors": {…}}

A contact of another account and a non-existent one get the same answer, so the response does not reveal whether the ID exists in another account.

getReferrers

Returns the contact's chain of referrers upwards: who invited them, who invited that person, and so on.

GETPOSThttps://watbot.org/api/v1/getReferrers
Parameter Type Required Description
contact_id number yes Contact ID
depth number no How many levels up to go: 1 to 1000. Default 10
is_flat boolean no true or 1 — return the referrers as a list; false or 0 — nested inside each other. The same in a GET query string: true, false, 1 or 0. Default false
Request
curl -X POST "https://watbot.org/api/v1/getReferrers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 4815170, "depth": 2}'
Response 200
{
  "data": {
    "id": 4815170,
    "bot_id": 12345,
    "phone": null,
    "email": null,
    "name": "Michael Brown",
    "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": "15550100123",
      "email": null,
      "name": "Emily Johnson",
      "address": null,
      "messenger": "telegram",
      "utm": [],
      "avatar": null,
      "telegram_id": "123456789",
      "telegram_username": "emily_j",
      "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": "Sarah Miller",
        "address": null,
        "messenger": "telegram",
        "utm": [],
        "avatar": null,
        "telegram_id": "323456782",
        "telegram_username": "sarah_m",
        "vk_user_id": null,
        "created_at": "2026-09-20T11:30:05+00:00",
        "unsubscribed_at": null,
        "tags": ["partner"],
        "variables": []
      },
      "tags": [],
      "variables": []
    },
    "tags": [],
    "variables": []
  }
}

The response holds the contact itself, and its referrer field holds the referrer with their own referrer, and so on down to depth. If there is no referrer, the contact has no referrer field.

With "is_flat": true, data is a list of referrers without the contact itself, from nearest to farthest. Each has a level field: -1 is the person who invited the contact, -2 is their referrer, and so on:

{
  "data": [
    {
      "id": 4815162,
      "name": "Emily Johnson",
      "…": "…",
      "tags": [],
      "variables": [],
      "level": -1
    },
    {
      "id": 4814901,
      "name": "Sarah Miller",
      "…": "…",
      "tags": ["partner"],
      "variables": [],
      "level": -2
    }
  ]
}

The contact fields in the list are the same as above — they are shortened here. No referrers — {"data": []}.

getReferrals

Returns the contact's first line — the people they invited personally — 15 per page.

GETPOSThttps://watbot.org/api/v1/getReferrals
Parameter Type Required Description
contact_id number yes Contact ID
filters[tag_name] string or array of strings no Only referrals that have these tags — all of them at once. The first 10 tags are used
page number no Page number, starting from 1. Default 1

Requesting referrals tagged "paid":

Request
curl -X POST "https://watbot.org/api/v1/getReferrals" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 4815162, "filters": {"tag_name": ["paid"]}}'
Response 200
{
  "data": [
    {
      "id": 4815170,
      "bot_id": 12345,
      "phone": null,
      "email": null,
      "name": "Michael Brown",
      "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": ["paid"],
      "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
  }
}

Referrals are sorted by ascending id. The page size cannot be changed. Request the next pages with the page parameter until links.next becomes null; send contact_id and the filter with every request — the URLs in links do not carry them.

getCountReferrals

Counts the contact's referrals: the whole network or a single line.

GETPOSThttps://watbot.org/api/v1/getCountReferrals
Parameter Type Required Description
contact_id number yes Contact ID
level number no Line number, from 1: 1 — people the contact invited personally, 2 — people invited by them, and so on. Without it, the whole network is counted
filters[tag_name] string or array of strings no Only referrals that have these tags — all of them at once. The first 10 tags are used

How many people are in the second line:

Request
curl "https://watbot.org/api/v1/getCountReferrals?contact_id=4815162&level=2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
Response 200
{
  "data": {
    "count": 7
  }
}

If the contact has not invited anyone, count is 0.

Here the number is in data.count, while getNumberOfContacts returns it in a top-level count, without data. This is historical and stays as is so as not to break existing integrations.