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.

Available features:

  • CleanTalk's Personal Blacklist or Whitelist feature helps you to block unwanted users and to allow users that were recognized as spammers.
  • Stop-Word feature allows you to block comments and nicknames which contain any word from your Stop-Word List.
  • Country-Blacklist  allows you to block all comments/registration to users from selected countries.

Notice: Stop-Word and Country-Blackist features are availabe after purchaising our Extra Package. Go to your Renewal Licence Page to see the details.

 

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