Skip to content

CheckAccount#

Test Postman

The method checks whether a Telegram messenger account exists on a phone number.

The method uses limits on the request rate per second.

Please note!

The system records when requests to check whether an account exists by phone number are sent frequently. This is especially suspicious when the same non-existent number is checked repeatedly. As a result, the messenger may impose temporary restrictions.

Request#

To check whether a Telegram messenger account exists, you need to execute a request at:

POST 
{{apiUrl}}/waInstance{{idInstance}}/checkAccount/{{apiTokenInstance}}

To get the apiUrl, idInstance and apiTokenInstance request parameters, refer to the Before you start section.

Request parameters#

Parameter Type Required Description
phoneNumber integer No* Phone number in international format (*required if username is not specified)
username string No* Telegram username that starts with the @ character (*required if phoneNumber is not specified)
force boolean No The parameter determines whether the cache should be ignored.
By default false - the method uses cached data.
With the value true it ignores the cache and sends the request directly to the Telegram server.

Request body example#

{
    "username": "@username"
}

{
    "phoneNumber": 79876543210,
    "force": true
}

Response#

Response fields#

Field Type Description
exist boolean Flag that a Telegram account exists on the phone number
chatId string chatId of the Telegram user on the phone number
username string Unique public username
phoneNumber integer Phone number in international format
fromCache boolean If true - the data was obtained from the cache
If false - directly from the Telegram server

Response body example#

A Telegram account is linked to the number

{
    "exist": true,
    "chatId": "10000000",
    "username": "@username",
    "phoneNumber": 79876543210,
    "fromCache": true
}

The number has no Telegram account or the number is hidden by privacy settings

{
    "exist": false,
    "chatId": ""
}

The instance is in the starting or notAuthorized status

{
    "status": false,
    "reason": "instance is starting or not authorized"
}

The request limit for the phone number by the method has been reached 

{
    "status": false,
    "data": {
        "status": "fail",
        "reason": "rate_limit_exceeded",
        "retryAfter": 11930619
    }
}

Both the phone number and the username are specified in the request

{
    "status": false,
    "reason": "request should contain 'phoneNumber' or 'username'"
}

Errors#

For the list of errors common to all methods, see the Common errors section

HTTP code Error identifier Description
400 Bad Request
Validation failed		 Validation error
400 Validation failed.
Details: Wrong format. 'phoneNumber' must contain only digits		 The number must contain only digits
200 rate_limit_exceeded The Telegram server returned an error because of frequent requests to various numbers within a few minutes. It is recommended to pause number checks on the instance for 2 hours.

Code examples#

import requests

url = "{{apiUrl}}/waInstance{{idInstance}}/checkAccount/{{apiTokenInstance}}"

payload = {
    "phoneNumber": 79876543210
}

response = requests.post(url, json=payload)

print(response.text.encode('utf8'))

curl --location '{{apiUrl}}/waInstance{{idInstance}}/checkAccount/{{apiTokenInstance}}' \
--header 'Content-Type: application/json' \
--data '{
    "phoneNumber": 79876543210
}'

var restTemplate = new RestTemplate();
var requestUrl = new StringBuilder();
requestUrl
    .append({{apiUrl}})
    .append("/waInstance").append({{idInstance}})
    .append("/checkAccount/")
    .append({{apiTokenInstance}});

var headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_JSON);

var jsonBody = "{\"phoneNumber\": 79876543210}";

var requestEntity = new HttpEntity<>(jsonBody, headers);

var response = restTemplate.exchange(requestUrl.toString(), HttpMethod.POST, requestEntity, String.class);
System.out.println(response);

var requestUrl = new StringBuilder();
requestUrl
    .append({{apiUrl}})
    .append("/Instance").append({{idInstance}})
    .append("/checkAccount/")
    .append({{apiTokenInstance}});

var response = Unirest.post(requestUrl.toString())
    .header("Content-Type", "application/json")
    .body("{\"phoneNumber\": 79876543210}")
    .asString();

System.out.println(response);

Sub CheckAccount()
    Dim url As String
    Dim RequestBody As String
    Dim http As Object
    Dim response As String

    ' The apiUrl, idInstance and apiTokenInstance values are available in console, double brackets must be removed
    url = "{{apiUrl}}/waInstance{{idInstance}}/checkAccount/{{apiTokenInstance}}"

    ' chatId - is the number to check Telegram
    RequestBody = "{""phoneNumber"":"79876543210"}"

    Set http = CreateObject("MSXML2.XMLHTTP")

    With http
        .Open "POST", url, False
        .setRequestHeader "Content-Type", "application/json"
        .Send RequestBody
    End With

    response = http.responseText

    Debug.Print response

    ' Outputting the answer to the desired cell
    Range("A1").Value = response

    Set http = Nothing
End Sub