API spam filter "check_message"

 

Required parameters:

  • method_name - method nam, must be 'check_message';
  • auth_key - API key. To obtain a key please get an account here https://cleantalk.org/register?platform=api;
  • sender_email - email for spam checking;
  • sender_ip - IP for spam checking;
  • js_on - is JavaScript enabled in user's browser;
  • submit_time - form submitting time in seconds;

There is the list of the necessary parametrs which hardly affect on filtration. Most of the requests will be marked as spam without them:

  • all_headers - HTTP-request headers (JSON encoded);
  • sender_nickname - sender nickname for spam checking;
  • message - text message for checking, can contain HTML-tags;
  • sender_info - information about sender, should be JSON encoded, next fields are mandatory:
    • REFFERRER - content of $_SERVER['HTTP_REFERER']
    • USER_AGENT - content of $_SERVER['HTTP_USER_AGENT']

 

Additional parameters:

Sending this parameters will improve filtration.

  • sender_info - any additional information about sender, should be JSON encoded.
  • response_lang - API response language;
  • post_info - additional information about message (JSON encoded, must contain key named 'comment_type');
  • stoplist_check - logical flag to check message via stop-words list (1 or 0) (should be enabled in account);

Examples:

Using Wget:

wget -O- --post-data='{"method_name":"check_newuser","auth_key":"your_acccess_key","sender_email":"stop_email@example.com","sender_nickname":"John Doe","sender_ip":"127.0.0.1","js_on":1,"submit_time":15}' https://moderate.cleantalk.org/api2.0

Using PHP: 

<?php session_start(); require_once (dirname(__FILE__) . '/cleantalk.class.php'); // Take params from config $config_url = 'http://moderate.cleantalk.org/api2.0/'; $auth_key = 'enter key'; // Set Cleantalk auth key if (count($_POST)) { $sender_nickname = 'John Dow'; if (isset($_POST['login']) && $_POST['login'] != '') $sender_nickname = $_POST['login']; $sender_email = 'stop_email@example.com'; if (isset($_POST['email']) && $_POST['email'] != '') $sender_email = $_POST['email']; $sender_ip = null; if (isset($_SERVER['REMOTE_ADDR'])) $sender_ip = $_SERVER['REMOTE_ADDR']; $js_on = 0; if (isset($_POST['js_on']) && $_POST['js_on'] == date("Y")) $js_on = 1; $message = null; if (isset($_POST['message']) && $_POST['message'] != '') $message = $_POST['message']; // The facility in which to store the query parameters $ct_request = new CleantalkRequest(); $ct_request->auth_key = $auth_key; $ct_request->agent = 'php-api'; $ct_request->sender_email = $sender_email; $ct_request->sender_ip = $sender_ip; $ct_request->sender_nickname = $sender_nickname; $ct_request->js_on = $js_on; $ct_request->message = $message; $ct_request->submit_time = time() - (int) $_SESSION['ct_submit_time']; //Additional parameters. You could the description at the bottom of the page. $ct = new Cleantalk(); $ct->server_url = $config_url; // Check $ct_result = $ct->isAllowMessage($ct_request); if ($ct_result->allow == 1) { echo 'Message allowed. Reason ' . $ct_result->comment; } else { echo 'Message forbidden. Reason ' . $ct_result->comment; } echo '<br /><br />'; } else { $_SESSION['ct_submit_time'] = time(); } ?>

HTML code:

<form method="post"> <label for="login">Login:<label> <input type="text" name="login" id="login" /> <br /> <label for="email">Email:<label> <input type="text" name="email" id="email" value="" /> <br /> <label for="message">Message:<label> <textarea name="message" id="message"></textarea> <br /> <input type="hidden" name="js_on" id="js_on" value="0" /> <input type="submit" /> </form> <script type="text/javascript"> var date = new Date(); document.getElementById("js_on").value = date.getFullYear(); </script>

Submit_time and js_on parameters are very important for checking. Submit_time is the difference between submitting form time and page accessing time. js_on can be calculated by evaluating some JavaScript code in browser and comparing with reference value on server side. See in example, how you can calculate them: https://cleantalk.org/help/api-without

Example of additional parameters using (PHP):

$sender_info = array( 'page_url' => htmlspecialchars(@$_SERVER['SERVER_NAME'].@$_SERVER['REQUEST_URI']), 'REFFERRER' => htmlspecialchars(@$_SERVER['HTTP_REFERER']), 'USER_AGENT' => htmlspecialchars(@$_SERVER['HTTP_USER_AGENT']), 'fields_number' => sizeof($_POST), );  $sender_info = json_encode($sender_info); if ($sender_info === false) $sender_info = '';  $ct_request->sender_info = $sender_info;  $ct_request->stoplist_check = 1;  $ct_request->all_headers = json_encode(apache_request_headers()); $post_info['comment_type'] = 'general_comment';  $post_info = json_encode($post_info); if ($post_info === false) $post_info = '';  $ct_request->post_info = $post_info;

More info can be found on our GitHub: [ https://github.com/CleanTalk/php-antispam ].

Response:

Server's response doesn't depend on the platform.

{
"stop_queue" : 0,
"inactive" : 0,
"version" : "7.47",
"spam" : 1,
"js_disabled" : 0,
"comment" : "*** Forbidden. Sender blacklisted. ***",
"codes" : "FORBIDDEN BL",
"blacklisted" : 1,
"fast_submit" : 0,
"account_status" : "1",
"id" : "433289e278ae059f8fc58914fc890de2",
"allow" : 0
}

Explanation:

  • stop_queue - stop queue for comment approvement (comment 100% is a spam);
  • spam - comment - spam, possible to send it to hand moderation is flag stop_queue == 0;
  • js_disabled - JavaScript is disabled;
  • comment - comment for server's decision or for another errors (wrong access key etc.);
  • codes - answer codes.
  • blacklisted - sender is in CleanTalk's blacklists;
  • fast_submit - to fast form submitting;
  • account_status - is account enabled or not (0 or 1);
  • id - message ID (helpful for our support),
  • allow - is message allowed (1) or not (0);

You could see the codes explanation at the bottom of this article: https://cleantalk.org/help/api-without.

 

This spam protection API should be used only for registration checking. For other purposes use you could use other methods: