CleanTalk Anti-Spam "check_bot" API method description

This method is the best to filter bots during the simple page viewing. Just run it in background and fire any block page/message if the cloud returns bot factor (allow = 0). Place the example whenever you like, the code does not interrupt visitors and does not affect conversations.

1. Collect web-form data.
2. Send data JSON via a POST request to https://moderate.cleantalk.org/api2.0
3. Parse the response and make a decision.
4. This method works in conjunction with the method fronted_data. The method frontend_data has to be used through the inclusion of the following javascript file in the site code.
   

   <script src="https://moderate.cleantalk.org/ct-bot-detector-wrapper.js"></script>

Request

Data JSON Example

{
    "method_name":"check_bot",
    "auth_key":"your_acccess_key",
    "message_to_log":"some useful text you can see in the log",
    "event_token":"sha_256_string_of_event_token",
    "agent":"your_super_user_agent v.1.77",
    "event_type":"GENERAL_BOT_CHECK"|"CONTACT_DECODING",
    "event_javascript_data":"",
    "browser_sign":"",
    "sender_ip":"127.0.0.1",
    "page_url":"https://your-great-site.com/page1",
    "sender_info": {
        "REFERRER": "https:/referrer-site.com",
        "USER_AGENT": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3835.0 Safari/537.36"
    }
}

Data Processing

Necessary information about the data processing.

Required Parameters

These parameters are required.

Additional parameters

These parameters will improve filtration.

Response

Response example

The server's response is independent of the platform.

{
	"allow" : 1,
	"bot_expectation" : "0.2",
	"ip_frequency_10min" : 2,
    "ip_frequency_1hour" : 0,
    "ip_frequency_24hour" : 0,
	"comment" : "Allowed",
}

Response Explanation

Code Examples

Using Wget

CLI example

wget -O- --post-data='{"method_name":"check_bot","auth_key":"your_acccess_key","sender_ip":"127.0.0.1"}' https://moderate.cleantalk.org/api2.0

Using PHP

PHP backend

Download the CleanTalk library here. The library folder must be placed in the same path as the PHP file. Also, you can install the library via Composer.

Files Structure:

CheckBot
    CheckBot.php
    CheckBotConfig.php
lib
    Cleantalk.php
    cleantalk-php-patch.php
    CleantalkAntispam.php
    CleantalkAPI.php
    CleantalkHelper.php
    CleantalkRequest.php
    CleantalkResponse.php
    CleantalkResponse.php
    TransportException.php
search_form_with_check_bot.php
searchform.html

File search_form_with_check_bot.php

                                

                                    
                                    Copy link
                                    
                                    
                                    Copy code
                                
                               <?php

require_once(dirname(__FILE__) . '/lib/Cleantalk.php');
require_once(dirname(__FILE__) . '/lib/CleantalkRequest.php');
require_once(dirname(__FILE__) . '/lib/CleantalkResponse.php');
require_once(dirname(__FILE__) . '/lib/CleantalkHelper.php');
require_once(dirname(__FILE__) . '/CheckBot/CheckBot.php');
require_once(dirname(__FILE__) . '/CheckBot/CheckBotConfig.php');

if ( empty($_POST) ) {
    return;
} else {
    $post = $_POST;
}

handle_search_form($post);

/**
 * Main search from handler.
 * @param $post
 * @return void
 * @throws Exception
 */
function handle_search_form($post)
{
    if ( empty($post['search_field']) ) {
        return;
    }

    // set new CheckBotConfig
    $config = new CheckBotConfig(
        array(
            /*
             * Your CleanTalk access key. This example get the key from the system environment,
             * you can use your onw way or insert key string directly.
             */
            'access_key' => getenv("CLEANTALK_TEST_API_KEY"),
            /*
             * Set this to true if you trust CleanTalk decision and do not want
             * to perform additional custom checks
             */
            'trust_cleantalk_decision' => false,
            /*
             * Message for blocked visitor
             */
            'common_block_message' => 'Visitor blocked. It seems to be a bot.',

            /**
             * Attention! Settings below affected only if the property "trust_cleantalk_decision
             * is set to false.
             */

            /*
             * Custom check - set maximum bot probability percentage. For example, 0.5 is 50%.
             * If CleanTalk API responsed
 with bot_expectation 0.53 - visitor will be blocked,
             * if 0.47 - passed.
             */
            'bot_expectation' => 0.5,
            /*
             * Custom checks - set how to block a visitor whose IP address detected by CleanTalk
             * service in the period. For example, if CleanTalk response contains
             * ip_frequency_24hour = 1000, and the config property ip_frequency_24hour = 500,
             * visitor will be blocked.
             */
            'ip_frequency_24hour' => 50,
            'ip_frequency_1hour' => 15,
            'ip_frequency_10min' => 5,
            /*
             * Set to true if you want to see the log, false otherwise.
             */
            'do_log' => true
        )
    );
    $bot_checker = new CheckBot($post, $config);

    //call visitor check
    $is_bot = $bot_checker->check()->getVerdict();
    if ( $is_bot ) {
        die ($bot_checker->getBlockMessage());
    }

    //implement your search form handler here replacing echo
    echo('You searched for this: ' . $post['search_field']);
}

Class CheckBot/CheckBot.php

                                

                                    
                                    Copy link
                                    
                                    
                                    Copy code
                                
                               <?php

use Cleantalk\Cleantalk;
use Cleantalk\CleantalkRequest;
use Cleantalk\CleantalkResponse;

class CheckBot
{
    /**
     * Configuration obj.
     * @var CheckBotConfig
     */
    private $config;
    /**
     * $_POST
     * @var array
     */
    private $post;
    /**
     * Bot detector JS library event token
     * @var string
     */
    private $event_token;
    /**
     * CheckBot final verdict. True if visitor is bot.
     * @var bool
     */
    private $verdict = false;
    /**
     * The message for blocked visitor.
     * @var string
     */
    private $block_message = '';

    public function __construct(array $post_data, CheckBotConfig $config)
    {
        $this->post = $post_data;
        $this->config = $config;
    }

    /**
     * Get Bot-Detector event token form POST data.
     * @return string
     */
    private function getEventToken()
    {
        $event_token = isset($this->post['ct_bot_detector_event_token'])
            ? $this->post['ct_bot_detector_event_token']
            : '';
        if ( $event_token && is_string($event_token) && strlen($event_token) === 64 ) {
            return $event_token;
        }
        return '';
    }

    private function setEventToken($event_token)
    {
        $this->event_token = $event_token;
    }

    /**
     * Call check_bot CleanTalk API method. Return false on failure, CleantalkResponse obj on succes.
     * @return CleantalkResponse|false
     */
    private function checkBotApiCall()
    {

        $ct_request = new CleantalkRequest();
        $ct_request->event_token = $this->event_token;
        $ct_request->auth_key = $this->config->access_key;

        if ( empty($ct_request->auth_key) ) {
            $this->writeLog('CleanTalk check_bot: access key is empty. Check skipped.');
            return false;
        }

        if ( empty($ct_request->event_token) ) {
            $this->writeLog('CleanTalk check_bot: event token not found. Check skipped.');
            return false;
        }

        $ct = new Cleantalk();
        $ct->server_url = $ct_request::CLEANTALK_API_URL;
        $ct_result = $ct->checkBot($ct_request);
        $this->writeLog('CleanTalk check_bot result: ' . var_export($ct_result, true));

        return $ct_result;
    }

    public function getVerdict()
    {
        return $this->verdict;
    }

    public function getBlockMessage()
    {
        return $this->block_message;
    }

    /**
     * Makes decision if visitor is bot using CleanTalk libraries, exactly check_bot method.
     * @return CheckBot
     */
    public function check()
    {
        //get event token
        $this->setEventToken($this->getEventToken());
        //call CleanTalk API
        $check_bot_result = $this->checkBotApiCall();

        //handle response
        if ( false === $check_bot_result ) {
            $this->verdict = false;
            return $this;
        }

        if (!empty($check_bot_result->errstr)) {
            $this->writeLog('CleanTalk check_bot failed. Check method call parameters. Error: ' . $check_bot_result->errstr);
            $this->verdict = false;
            return $this;
        }

        $this->block_message = !empty($this->config->common_block_message)
            ? $this->config->common_block_message
            : $check_bot_result->comment;

        //block if CleanTalk decision is enough for you
        if ( $this->config->trust_cleantalk_decision ) {
            $this->verdict = isset($check_bot_result->allow) && $check_bot_result->allow != 1;
            $this->writeLog('CleanTalk check_bot: visitor blocked on CleanTalk decision.');
            return $this;
        }

        //run custom checks for response properties
        foreach ( $this->config->custom_checks_properties as $property ) {
            if ( $check_bot_result->$property > $this->config->$property ) {
                $this->verdict = true;
                $this->writeLog('CleanTalk check_bot: visitor blocked by custom setting: ' . $property . ' > ' . $this->config->$property);
                return $this;
            }
        }

        return $this;
    }

    /**
     * Writes log in PHP error log.
     * @param $msg
     * @return void
     */
    private function writeLog($msg)
    {
        if ( $this->config->do_log && is_string($msg) && !empty($msg)) {
            error_log($msg);
        }
    }
}

Class CheckBot/CheckBotConfig.php

                                

                                    
                                    Copy link
                                    
                                    
                                    Copy code
                                
                               <?php

class CheckBotConfig
{
    private $obligatory_properties = array('access_key',
        'trust_cleantalk_decision',
    );

    public $custom_checks_properties = array('bot_expectation',
        'ip_frequency_24hour',
        'ip_frequency_1hour',
        'ip_frequency_10min',
    );

    public $access_key = '';
    public $trust_cleantalk_decision = true;
    public $common_block_message = 'Visitor blocked. It seems to be a bot.';
    public $do_log = true;
    public $bot_expectation = 0.5;
    public $ip_frequency_24hour = 50;
    public $ip_frequency_1hour = 15;
    public $ip_frequency_10min = 5;

    public function __construct($params)
    {
        if ( !$this->isObligatoryParamsPresented($params) ) {
            throw new \Exception('CheckBot config: not enough params set.');
        }
        foreach ( $params as $param_name => $param ) {
            if ( property_exists(static::class, $param_name) ) {
                $type = gettype($this->$param_name);
                $this->$param_name = $param;
                settype($this->$param_name, $type);
            }
        }
    }

    public function __get($name)
    {
        return property_exists(static::class, $name) ? $this->$name : null;
    }

    private function isObligatoryParamsPresented($params)
    {
        return empty($this->obligatory_properties) ||
            count(array_intersect($this->obligatory_properties, array_keys($params))) === count(
                $this->obligatory_properties
            );
    }
}

HTML frontend

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
    <script src="https://moderate.cleantalk.org/ct-bot-detector-wrapper.js"></script>
</head>
<body>
<form method="post" action="check_bot.php">
    <label for="search_field">What do you search?</label>
    <input type="text" name="search_field" id="search_field" /> <br />
    <input type="submit" />
</form>
</body>
</html>

More info can be found on our GitHub.