Lookup Query

This method allows you to lookup a user, chat or channel in the SpamProtection database, this method does not require authentication and there are no rate limits.

Endpoint Parameters

Parameter Name	Default Value	Required	Description
query	`NULL`	True	The ID, Private Telegram ID or Username (With or without @)

Example Success Response

{
  "success":true,
  "response_code":200,
  "results":{
    "private_telegram_id":"TEL-244c681c7ca23d46e073414a7f3933da41ac031a924cea33b406027823c57439-f568d408",
    "entity_type":"channel",
    "attributes":{
      "is_blacklisted":true,
      "blacklist_flag":"0xSPAM",
      "blacklist_reason":"Spam / Unwanted Promotion",
      "original_private_id":null,
      "is_potential_spammer":false,
      "is_operator":false,
      "is_agent":false,
      "is_whitelisted":false,
      "intellivoid_accounts_verified":false,
      "is_official":true
    },
    "language_prediction":{
      "language":"en",
      "probability":0.8460620768954751
    },
    "spam_prediction":{
      "ham_prediction":0.0199941052,
      "spam_prediction":0.000005399803
    },
    "last_updated":1598047387
  }
}

Results Object Structure

Name	Type	Description
private_telegram_id	`string`	The private Telegram ID of the entity
entity_type	`string`	The entity type, can be user, bot, group, supergroup or channel
attributes	`attributes`	The attributes of the entity, such as blacklist information and so on.
language_prediction	`language_prediction`	Information about the generalized language prediction
spam_prediction	`spam_prediction`	Information about the generalized spam prediction
last_updated	`int`	The Unix Timestamp of when this was last updated in the database

Attributes Object Structure

Name	Type	Description
is_blacklisted	`boolean`	Indicates if this entity was blacklisted by a operator or agent
blacklist_flag	`string\|null`	If the entity is blacklisted, the blacklist flag will be available otherwise it will be null
blacklist_reason	`string\|null`	If the entity is blacklisted, a user friendly message of the blacklist flag will be available otherwise it will be null
original_private_id	`string\|null`	If the entity was blacklisted for 0xEVADE then the original private telegram ID (ptid) will be available, otherwise it will be null
is_potential_spammer	`boolean`	Indicates if SpamProtection believes that this user may be a potential spammer based on past activities
is_operator	`boolean`	Indicates if this user is an operator for SpamProtectionBot
is_agent	`boolean`	Indicates if this user is an agent that automatically reports spam to SpamProtectionBot (Userbot Agent)
is_whitelisted	`boolean`	Indicates if this user is whitelisted and cannot be blacklisted or seen as a potential spammer
intellivoid_accounts_verified	`boolean`	Indicates if this user has verified their Telegram Account with Intellivoid Accounts
is_official	`boolean`	Indicates if this entity is deemed official by Intellivoid Technologies

Language Prediction Object Structure

Name	Type	Description
language	`string\|null`	The ISO 639-1 language code predicted by SpamProtectionBot, if no prediction is available then it will be null
probability	`float\|int\|null`	The probability (confidence) of this generalized language prediction, if no prediction is available then it will be null

Spam Prediction Object Structure

Name	Type	Description
ham_prediction	`float\|int\|null`	The probability (confidence) of this generalized ham (not spam) prediction, if no prediction is available then it will be null
spam_prediction	`float\|int\|null`	The probability (confidence) of this generalized spam prediction, if no prediction is available then it will be null

No Results Found Response

This response is given when the requested query does not exist in the SpamProtection Database

{
  "success":false,
  "response_code":404,
  "error":{
    "error_code":10,
    "type":"CLIENT",
    "message":"Unable to resolve the query"
  }
}

In conclusion

This method is publicly available for everyone to access and use for whatever purpose for as long as it is not for malicious intents. This part of the documentation will quickly explain what the important attributes mean and how you should deal with it.

Blacklisted Entities

Blacklisted entities applies to both a user and channel, if the entity is blacklisted then the attributes blacklist_flag, blacklist_reason and optionally original_private_id will become available to provide further information about the blacklist reason, blacklisted users were blacklisted manually by an operator or agent due to abusive behaviors and in such cases they can appeal for their blacklist to be removed via our support chat @SpamProtectionSupport except for 0xCACP

These users should be banned or restricted from public chats upon joining/sending a message

Potential Spammers

These users are potentially a smaller threat than blacklisted users, a potential spammer only happens when their spam prediction is higher than their ham prediction. (Aka sending nothing but spam). This flag is not permanent and can be reverted simply by not sending spam as often. This flag is usually raised by spam bots and not normally by normal users.

These users should be temporarily restricted upon joining groups or require to pass a captcha validation before being able to send anything.