Lookup

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.
Parameter NameDefault ValueRequiredDescription
queryNULLTrueThe 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

NameTypeDescription
private_telegram_idstringThe private Telegram ID of the entity
entity_typestringThe entity type, can be user, bot, group, supergroup or channel
attributesattributesThe attributes of the entity, such as blacklist information and so on.
language_predictionlanguage_predictionInformation about the generalized language prediction
spam_predictionspam_predictionInformation about the generalized spam prediction
last_updatedintThe Unix Timestamp of when this was last updated in the database

Attributes Object Structure

NameTypeDescription
is_blacklistedbooleanIndicates if this entity was blacklisted by a operator or agent
blacklist_flagstring|nullIf the entity is blacklisted, the blacklist flag will be available otherwise it will be null
blacklist_reasonstring|nullIf the entity is blacklisted, a user friendly message of the blacklist flag will be available otherwise it will be null
original_private_idstring|nullIf the entity was blacklisted for 0xEVADE then the original private telegram ID (ptid) will be available, otherwise it will be null
is_potential_spammerbooleanIndicates if SpamProtection believes that this user may be a potential spammer based on past activities
is_operatorbooleanIndicates if this user is an operator for SpamProtectionBot
is_agentbooleanIndicates if this user is an agent that automatically reports spam to SpamProtectionBot (Userbot Agent)
is_whitelistedbooleanIndicates if this user is whitelisted and cannot be blacklisted or seen as a potential spammer
intellivoid_accounts_verifiedbooleanIndicates if this user has verified their Telegram Account with Intellivoid Accounts
is_officialbooleanIndicates if this entity is deemed official by Intellivoid Technologies

Language Prediction Object Structure

NameTypeDescription
languagestring|nullThe ISO 639-1 language code predicted by SpamProtectionBot, if no prediction is available then it will be null
probabilityfloat|int|nullThe probability (confidence) of this generalized language prediction, if no prediction is available then it will be null

Spam Prediction Object Structure

NameTypeDescription
ham_predictionfloat|int|nullThe probability (confidence) of this generalized ham (not spam) prediction, if no prediction is available then it will be null
spam_predictionfloat|int|nullThe 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.