# Telegram Buyer Search — Fresh Requests to Buy, Hire & Rent (`telegrambest/telegram-lead-finder`) Actor

Find people already asking to buy, hire or rent in public Telegram groups. Get a concise English need, original text, country, freshness, source link and why it matched. TGDen — Telegram Intelligence.

- **URL**: https://apify.com/telegrambest/telegram-lead-finder.md
- **Developed by:** [TGDen — Telegram Intelligence](https://apify.com/telegrambest) (community)
- **Categories:** Lead generation, Social media, AI
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $8.00 / 1,000 buyer requests

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Telegram Buyer Search

**Telegram scrapers give you messages. TGDen gives you people already asking to buy.**

**TGDen — Telegram Intelligence** finds dated requests to buy, rent or hire across monitored public Telegram groups. Read the English need, check the original, then open the source.

**Proof snapshot · 23 October 2026:** Vietnam housing demand contained **1,011 unique request texts across 122 source groups in 30 days** (Demand Map snapshot at 14:50 UTC). These are classified request texts, not unique people or completed purchases. The five genuine rental requests below were read back from production. No Telegram login is needed.

### Five real buyer requests

| English need | Original request | Geo | Posted | Telegram |
| --- | --- | --- | --- | --- |
| Looking to rent a place starting 29 Oct for at least 3 months for a couple, budget up to 15,000 RUB per month. | здравствуйте   подскажите где можно переснять жилье с 29.10  планируем на долгий срок от 3-х мес  семейная пара  до 15000 руб в мес | VN | 2026-10-23 12:59:13 UTC | [source](https://t.me/nyachang_chatask/113103) |
| Looking to rent an apartment with a kitchen in Nha Trang, budget up to 10 million, for 2 months. | Сниму квартиру с кухней, Нячанг, до 10 млн, срок 2 месяца | VN | 2026-10-23 11:59:57 UTC | [source](https://t.me/rent_vietnam/110122) |
| Looking to rent an apartment in Nha Trang for 60 days. | Сниму квартиру в нячанге на 60 дней | VN | 2026-10-23 10:25:16 UTC | [source](https://t.me/rent_vietnam/110112) |
| Looking to rent an apartment for one month in central Nha Trang. | Девочки всем привет, подскажите 🙏  Есть ли вариант снять квартиру на месяц?  В центре нячанга  Может кто-то что-то знает? | VN | 2026-10-23 09:09:08 UTC | [source](https://t.me/nhatranggirls_ask/24363) |
| Looking for a one‑room or studio apartment for a young couple without children or pets, move‑in date 25 Oct 2026. | Всем привет.  Ищем однушку или студию.  Молодая пара без детей и животных. С 25.10.2026 можем заехать | VN | 2026-10-23 04:40:58 UTC | [source](https://t.me/nhatrang_house/218026) |

Country is a classifier label; a city may be mentioned in the text or the source group. These are real source messages, not invented examples. English summaries are optional AI enrichment: the original remains available if enrichment is still pending.

### Run this example

[**Open the ready Nha Trang apartment search →**](https://apify.com/telegrambest/telegram-lead-finder/examples/nha-trang-apartment-buyers)

[See the completed public example: 10 real requests →](https://api.apify.com/v2/datasets/6qun5pjeyaZ0ySJpp/items?signature=MC4xNzkzOTgxMjA0MzU4LjFmZWVLNVoxcm54emRWRDJYRlVGWg)

Owner-account acceptance run on 23 October 2026; this is a product sample, not a customer or payment claim.

The example opens with category, country and local city spellings filled in. Review its maximum charge, start it, then open the dataset. Or use the same input:

```json
{
  "categories": ["realty"],
  "countries": ["vn"],
  "mustInclude": ["Nha Trang", "Нячанг"],
  "days": 3,
  "maxResultsPerQuery": 10
}
```

The default table starts with **English need → original text → country → age in minutes → posted time → source link → why matched**. `whyMatched` names the classification and applied filters; a semantic score is similarity, not a conversion probability. `requestEnStatus=pending` means the separate translator will catch up; saving and finding the original does not wait for it.

### Cost

**$0.005 per run start + $0.008 per buyer request delivered.** With the 256 MB memory limit there is one start event. Ten billable results cost about **$0.085** in Actor fees. Zero matches incur only the start fee. Prices and any platform charges shown by Apify at launch are authoritative.

Set **Maximum charge per run** before starting (default $0.50). Delivery stops when the remaining budget cannot pay for another result; duplicate results are not billed twice in a run. Apify free-plan accounts receive at most 50 billable results per run. The amount of data in a snapshot may be larger than your budget permits.

### Discover a market first

[Demand Map](https://apify.com/telegrambest/telegram-demand-map) is a separate starting point: compare where demand exists, then open a TGDen Buyer Search preview for the selected market, with a ready input for this Actor. Use Buyer Search when you already know what you sell.

### Technical notes and limits

Only classified public requests are returned. Direct intent is the default; add soft, latent or hiring deliberately. Sellers, obvious spam and normalized duplicate texts are filtered, but classification is fallible. Read each original before acting. Semantic search alone does not enforce a city: use `mustInclude` and local spellings. Matches can use the group name as location context.

Coverage is partial. The chosen 1–30 day window uses the original `postedAt`; ingestion is not instantaneous. English needs are independently cached and retried; a missing translation never deletes or delays the original. A changed full source cannot reuse a stale summary, even if its displayed excerpt stays the same. The `text` excerpt is capped at 1,000 characters; `originalTruncated` flags longer sources. English enrichment reads the masked full captured source (up to 8,000 characters). Translation may omit nuance, and the linked original is authoritative.

The dataset contains delivered rows. `OUTPUT` records counts, source timings and explicit `results`, `valid_zero_result`, `limited` or `incomplete`. A failed source fails the run instead of becoming a successful empty result. This tool reads public catalog data and does not contact anyone.

### API and scheduled runs

Use the same JSON input with the public Actor API. Keep your Apify token in an environment variable.

```bash
curl -X POST \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  --data @input.json \
  "https://api.apify.com/v2/acts/telegrambest~telegram-lead-finder/run-sync-get-dataset-items?memory=256&timeout=180&maxTotalChargeUsd=0.50"
```

For longer runs use Apify's asynchronous run endpoint and fetch the dataset after completion. Where available, `onlyNew=true` remembers delivered items for this Actor and your account so scheduled searches skip them. Keep it off when you want a full repeatable snapshot.

### The family

[Buyer Search](https://apify.com/telegrambest/telegram-lead-finder) · [Groups](https://apify.com/telegrambest/telegram-group-discovery) · [Similar Groups](https://apify.com/telegrambest/telegram-similar-groups) · [Channels](https://apify.com/telegrambest/telegram-channel-discovery) · [Bots](https://apify.com/telegrambest/telegram-bot-finder) · [Username Checker](https://apify.com/telegrambest/telegram-entity-enrichment) · [Marketplace Ads](https://apify.com/telegrambest/telegram-classifieds) · [Prices](https://apify.com/telegrambest/telegram-market-prices) · [Demand Map](https://apify.com/telegrambest/telegram-demand-map)

Questions or a bad result? Open an issue on this Actor and include the run link and expected behavior. Never post tokens or Telegram sessions.

# Actor input Schema

## `categories` (type: `array`):

Choose at least one category or a country below. Requests are classified before search; use the dated originals to check that each result fits your need.

## `countries` (type: `array`):

Optional with a category, enough on its own. Two-letter codes of the country where the need is, e.g. 'AE', 'TH', 'TR'. A request gets a country when the message or its group names the place.

## `intentTypes` (type: `array`):

Direct — asks to buy, hire or rent now. Soft — asks how to solve their own problem or what it costs. Latent — describes a need without asking. Hiring — job vacancies. Default: direct only.

## `days` (type: `integer`):

How many days back to search. Fresh requests are the valuable ones — for a daily feed use 1-2 days with 'Only requests I have not received yet'.

## `maxResultsPerQuery` (type: `integer`):

Upper limit of requests per run, up to 1000 (per phrase when you add phrases below). You pay only for requests actually delivered. On the Apify free plan a run returns at most 50 requests.

## `onlyNew` (type: `boolean`):

For scheduled monitoring: skip requests this Actor already delivered to your account in earlier runs, so a daily run returns and charges only new ones. Leave off for one-off searches (and when an AI agent serves many people from one account).

## `queries` (type: `array`):

One phrase per line, in any language, written the way the asker would — e.g. 'need a landing page', 'looking for a villa in Phuket'. Each phrase is a separate search inside your categories. Leave empty to get every labeled request of the chosen categories.

## `matchStrictness` (type: `string`):

Only with phrases: how close a request must be. 'Strict' returns fewer, very close requests; 'Broad' returns more, including related needs.

## `mustInclude` (type: `array`):

Optional. Keep only requests where the message or the group name mentions at least one of these words. Matching is by word start, so 'Phuket' also matches 'Phuket's'. Add spellings in other languages too, e.g. 'Dubai', 'Дубай'. The way to pin a city inside a country, or a niche inside a category.

## `excludePhrases` (type: `array`):

Optional. Drop requests that contain any of these words or phrases, e.g. 'free', 'internship'.

## `languages` (type: `array`):

Optional. Keep only requests written in these languages. Leave empty for all languages.

## `minChatMembers` (type: `integer`):

Optional. Skip requests from groups smaller than this number of members.

## `demandNiche` (type: `string`):

Optional country × niche handoff from Demand Map. Uses the same classified need family.

## `entryPoint` (type: `string`):

Source of this saved search, used only for aggregate funnel measurement.

## Actor input object example

```json
{
  "categories": [
    "realty"
  ],
  "countries": [
    "AE",
    "TH"
  ],
  "intentTypes": [
    "direct"
  ],
  "days": 7,
  "maxResultsPerQuery": 20,
  "onlyNew": false,
  "queries": [
    "looking for a villa in Phuket",
    "need an accountant for a company in Dubai"
  ],
  "matchStrictness": "balanced",
  "mustInclude": [
    "Phuket",
    "Пхукет"
  ],
  "excludePhrases": [
    "free",
    "unpaid"
  ],
  "minChatMembers": 0,
  "entryPoint": "direct"
}
```

# Actor output Schema

## `overview` (type: `string`):

Dated demand messages from public Telegram groups with category, country, message text and t.me source link

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "categories": [
        "realty"
    ],
    "maxResultsPerQuery": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("telegrambest/telegram-lead-finder").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "categories": ["realty"],
    "maxResultsPerQuery": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("telegrambest/telegram-lead-finder").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "categories": [
    "realty"
  ],
  "maxResultsPerQuery": 20
}' |
apify call telegrambest/telegram-lead-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,telegrambest/telegram-lead-finder"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/vt39J9JxDskygYdoa/builds/xeaVznMeeubeuCbEW/openapi.json