NexCheck-筛号平台
As of the latest specifications in August 2026, the public Telegram Bot API endpoints do not include a reverse phone number lookup, which directly explains why the Telegram screening hit rate is so low. Many teams misinterpret "no result" as an invalid list, overlooking systematic deviations caused by protocol boundaries and rate limiting. Tools like NexCheck, by independently retaining unknown statuses and uniformly handling backoff logic, demonstrate that optimizing the social platform screening process engineering-wise is key to improving data usability.
How Telegram phone number parsing works: What happens server-side during a single query
In the underlying MTProto protocol, when the contacts.resolvePhone method is executed, the server first checks whether the call frequency exceeds the anti-throttling limit of once every 3 seconds, then verifies whether the target user's privacy settings allow strangers to be found via phone number. If any of these checkpoints fail, the server returns no user information. This means that "not found" is not due to a single cause but is a shared empty result for multiple server states. Therefore, the actual hit rate will naturally be lower than the proportion of truly registered users in the list, as some genuine users are excluded from valid responses due to privacy protection or rate-limiting windows.
Protocol layer: No reverse phone number lookup endpoint in Telegram Bot API
Many developers wonder Can Telegram Bot find users by phone number? The answer is no. The Bot API is an independent HTTP server interface, and among its publicly documented endpoints, no method supports inputting a phone number to reverse-query a Telegram user ID or registration status. Bots can only passively receive a Contact object that a user actively sends in a private chat. Any script that concatenates a query request based on a Bot token will theoretically have a hit rate close to zero, regardless of list quality. The first step in self-inspection is to confirm whether the script calls the Bot API's HTTP endpoints or MTProto client methods; the former cannot achieve bulk proactive probing.
Privacy layer: After disabling "Find me by phone number," the returned value is identical to that for unregistered numbers
Telegram official settings offer the privacy option "Who can find me by phone number." When a user tightens this to "Contacts only," non-contacts searching by phone number cannot resolve user information, and the external result is exactly the same as for an unregistered number. This raises another common question: Is a user not registered if the phone number cannot be found on Telegram? Technically, these two cases are indistinguishable. The stronger the privacy awareness and the higher the value of old users in a list, the more likely they are counted as "misses." Therefore, a low hit rate does not mean the list is fake; it may trigger privacy shielding. External tools cannot definitively differentiate between privacy restrictions and non-registration at the protocol level—this is an inherent characteristic of platform design.
Rate limiting layer: Why results during the 3-second debounce and FLOOD_WAIT_%d period are unreliable
For contacts.resolvePhone, the official documentation explicitly requires clients to implement debouncing, with a maximum call frequency of once every 3 seconds. Exceeding this triggers an RPC 420 FLOOD_WAIT_%d error, where the dynamic seconds indicate the server-mandated waiting time. If requests continue during the penalty period, the wait time increases exponentially or even leads to a ban. Engineering evidence shows that once rate-limited or degraded, even genuinely registered numbers return empty matches. "Misses" within this window are false negatives. What does Telegram FloodWait mean? It is not just an error; it is a marker of data contamination. To diagnose, inspect logs for 420 errors, identify the contaminated batch range, and treat results from that period as invalid for list validation.
Comparison of the three layers: diagnosis order and key differences
To accurately pinpoint the root cause, combine observable evidence for layered troubleshooting. The table below lists key differences and corresponding actions for each layer:
| Layer | Trigger Condition | Observable Evidence | Impact on Hit Rate | Corresponding Action |
|---|---|---|---|---|
| Protocol | Attempting reverse lookup via Bot API | Call endpoint is HTTP/Bot API | Total zero (near 0%) | Switch to MTProto client methods |
| Privacy | User enabled "Contacts only" privacy | Same number returns empty across different accounts | Partial missing (high-value users prone to miss) | Keep "unknown" tier; do not mark as unregistered |
| Rate limiting | Call frequency exceeds once per 3 seconds | Logs show 420 FLOOD_WAIT errors | Entire batch contaminated (including genuine registrations) | Back off according to returned seconds; rerun contaminated subset |
Diagnosis order should follow: confirm interface type first, then examine wait times and error logs, and only then suspect list quality. Blindly rescanning lists without resolving rate limiting and interface issues only increases the risk of bans.
How to calculate hit rate meaningfully: Denominator, unknown tier, and contaminated batches
Including all "misses" in the numerator makes the hit rate meaningless. What is a normal Telegram screening hit rate? Without an official benchmark, use your own historical batches as a reference line, not external numbers. A sound approach is to first exclude batches within rate-limiting windows, then combine privacy-blocked and unregistered into a separate "unknown" statistic, ultimately forming a three-tier data model: registered / unregistered / unknown. Only under this model can ratios be compared across batches. For example, if the "unknown" proportion is excessively high in a batch, it may indicate widespread privacy tightening or overly aggressive rate limiting, not list failure. This distinction helps avoid harming high-net-worth, private users and provides a clear basis for subsequent data governance.
Scenario-based actions: When hit rate is abnormal, adjust interface, schedule, or data model
Different scenarios warrant different correction strategies to minimize losses. Here is a decision guide for common situations:
| Common Situation | Characteristic | Recommended Action | Notes |
|---|---|---|---|
| Total zero hits | Script uses Bot Token; no user returned | Switch to MTProto client method | Verify key and account permissions |
| Hit rate low but stable | Results reproducible; no frequent errors | Keep "unknown" tier; do not rescan | Analyze list source and privacy sensitivity |
| Results volatile with 420 errors | Same batch yields different results twice | Back off per FLOOD_WAIT seconds, then rerun | Only rerun contaminated subset; avoid full retry |
| Cross-platform hit rate varies | Same list performs well on other platforms | Set independent metrics per platform | Understand protocol differences; avoid direct comparison |
| List format messy | From unknown channels; contains special characters | Normalize to E.164 and deduplicate first | Format errors will cause direct request rejection |
For teams with self-built scripts, following social account registration detection best practices ensures data cleaning is front-loaded. When dealing with complex multi-platform number detection needs, a unified result field definition is crucial. To simplify operations, consider using mature batch screening result rerun mechanisms to automatically identify and isolate anomalous batches.
Frequently Asked Questions
Can a bot developed with the Bot API find out if someone is a Telegram user via phone number?
No. The Bot API does not provide an endpoint to reverse-query user status by phone number. Bots can only receive contact cards that users actively send. For batch detection, you must use an MTProto client library to call the resolvePhone method, noting account permissions and rate limits.
Does an undetected number mean the person is not registered?
Not necessarily. If the target set "Who can find me by phone number" to "Contacts only," non-contacts will also get an empty result, identical to an unregistered number. The protocol cannot distinguish between these two cases, so treat such results as "unknown" rather than "unregistered."
What does the number after 420 FLOOD_WAIT mean and how to handle it?
That number is the server-mandated seconds to wait before retrying. Continuing during this period worsens penalties or leads to a ban. Pause the batch, wait the specified seconds, then re-request, and ensure subsequent calls stay within the 3-second interval.
How many numbers can be processed in one batch and how to schedule intervals?
The official documentation does not specify a daily total limit but clearly states a minimum interval of 3 seconds between calls. In practice, reserve buffer based on network conditions and account weight, typically processing serially, avoiding concurrent requests that trigger stricter rate limits. For large lists, process in batches across time slots.
If someone changes privacy to "Contacts only," can they still be detected?
No, not by phone number. The resolvePhone method returns no user information, resulting in query failure. To contact such users, you must rely on indirect methods like shared group membership, username search (if enabled), or existing chat history; phone number reverse lookup cannot bypass this privacy setting.
Comments(0)