Описание API метода CleanTalk Anti-Spam "check_message"

Данный метод лучше всего подходит для форм, содержащих пользовательский контент (UGC), например: комментарии, отзывы или контактные формы.

1. Соберите данные с веб-формы.
2. Отправьте данные JSON через запрос POST на https://moderate.cleantalk.org/api2.0.
3. Проанализируйте ответ и примите решение.

Запрос

• Пример данных JSON
• Обработка данных
• Обязательные параметры
• Дополнительные параметры

Ответ

• Пример ответа
• Разъяснение ответов

Примеры кода

• Wget
• PHP
• Python
• NodeJS
• C#
• GoLang

Ссылки по теме

Запрос

Пример данных JSON

{
	"method_name":"check_message",
	"auth_key":"your_acccess_key",
	"sender_email":"stop_email@example.com",
	"sender_nickname":"John Doe",
	"sender_ip":"127.0.0.1",
	"event_token":"sha_256_string_of_event_token"
	"submit_time":15,
	"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"
		},
	"tz":"UTC+01",
	"phone":"+1237650009",
	"message": "Hello I am a spammer visit this https://badlinkexample.com"
}

Обработка данных

Необходимая информация об обработке данных.

Обязательные параметры

Данные параметры обязательны

Дополнительные параметры

Использование данных параметров улучшает качество фильтрации

Ответ

Пример ответа

       Ответ сервера не зависит от платформы.

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

Разъяснение ответов

Остальное — информационные флаги для отображения соответствующих сообщений посетителям сайта.

В коде ответа сервера вы также можете увидеть результат проверки адреса электронной почты на существование. Если заблокированный запрос содержит несуществующий адрес электронной почты, вы увидите следующий текст в поле кода ответа API: "FORBIDDEN EMAIL_NOT_EXISTS" Обратите внимание, что этот код будет отображаться только в том случае, если несуществующий адрес электронной почты является основной причиной блокировки.

Примеры кода

Wget

CLI 

wget -O- --post-data='{"method_name":"check_message","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

PHP

PHP backend

Скачайте библиотеку CleanTalk здесь. Папку с библиотекой нужно поместить в ту же папку, что и файл PHP. Также вы можете установить библиотеку через Composer.

<?php

use Cleantalk\Cleantalk;
use Cleantalk\CleantalkRequest;

session_start();

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');

// Take params from config
$config_url = 'http://moderate.cleantalk.org/api2.0/';
$auth_key = 'your_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'];
    }

    // 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->event_token = isset($_POST['ct_bot_detector_event_token'])
        ? $_POST['ct_bot_detector_event_token']
        : null;
    $ct_request->message = isset($_POST['message_field'])
        ? $_POST['message_field']
        : null;
    $ct_request->submit_time = isset($_SESSION['ct_submit_time'])
        ? time() - (int) $_SESSION['ct_submit_time']
        : null;
    // you can change comment type to "general_contact_form" to make the check more specified
    $ct_request->post_info = '{"comment_type":"general_comment"}';
    
    //Additional parameters.
    $ct = new Cleantalk();
    $ct->server_url = $config_url;

    //Check
    $ct_result = $ct->isAllowMessage($ct_request);
    if ($ct_result->allow == 1) {
        echo 'User allowed. Reason ' . $ct_result->comment;
    } else {
        echo 'User forbidden. Reason ' . $ct_result->comment;
        echo '<br /><br />';
    }
}
else {
    $_SESSION['ct_submit_time'] = time();
}

Параметры sumbit_time и event_token очень важны при проверке.

HTML frontend

<?php session_start(); $_SESSION['ct_submit_time'] = time();?>
<!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_message.php">
    <label for="login">Your name</label>
    <input type="text" name="login" id="login" /> <br />
    <label for="email">Your email:</label>
    <input type="text" name="email" id="email" value="" /> <br />
    <label for="message_field">Enter your message:</label>
    <textarea name="message_field" id="message_field"></textarea> <br />
    <input type="submit" />
</form>
</body>
</html>

Пример использования дополнительных параметров

$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->phone = '+1 123-456-78-90';
$ct_request->all_headers = json_encode(apache_request_headers());

Больше информации можно найти в нашем GitHub.

Python

Python Backend (Django)

Пример реализации класса CleanTalk. Поместите код в файл (что-то вроде cleantalk.py) и импортируйте модуль в код, где вам нужно его использовать.

#!/usr/bin/python
# coding=utf-8

from __future__ import unicode_literals

try:
    from urllib.request import urlopen, Request
    from urllib.parse import urlparse
    from urllib.parse import urlencode
    import os

except ImportError:
    from urllib import urlopen, Request, urlencode
    from urlparse import urlparse
    import os

import json


class CleanTalk:
    """Python API for CleanTalk.org"""
    VERSION = 1.2
    ENCODING = 'utf-8'
    user_agent = 'Mozilla/5.0'

    def __init__(self,
                 auth_key,
                 method_name,
                 server_url='https://moderate.cleantalk.org',
                 api_url='/api2.0',
                 connection_timeout=8,
                 agent=None):

        """
        This method constructs a new CleanTalk object and returns it.
        :param auth_key:
        :param server_url:
        :param api_url:
        :param connection_timeout:
        :param method_name:
        """
        self.__server_url = server_url
        self.__api_url = api_url
        self.__connection_timeout = connection_timeout
        self.__method_name = method_name
        self.__auth_key = auth_key
        if agent:
            self.__agent = agent
        else:
            self.__agent = 'python-api-' + str(CleanTalk.VERSION)

    def request(self,
                sender_email,
                message='',
                sender_ip='',
                sender_nickname='',
                js_on=1,
                post_info=None,
                sender_info=None,
                submit_time=None,
                event_token=None):
        """
        This method will dispatch call to servers.
        Exceptions can be raised: ValueError on bad json, URLError on bad url, HTTPError, HTTPException on http-error
        :param sender_email: Required. Email IP of the visitor.
        :param message: Visitor's message if applicable.
        :param sender_ip: IP address of the visitor. You can skip this field if event_token is provided.
        :param sender_nickname: Nickname of the visitor
        :param js_on: if javascript is enabled on visitors side
        :param sender_info: additional sender info
        :param submit_time: the time from page start to submit event
        :param post_info: info about the page
        :param event_token: token for check data from frontend
        :return: dictionary, where:
                    KEY                     VALUE
                -----------             --------------------
                allow                   0|1 - spam or not comment/registration
                id                      MD5_HEX - unique request ID
                comment                 string - description about request from server
                stop_queue              0|1 - should comment move to site's moderation queue or not
                inactive                0|1 - should registration move to inactive state or not
        """
        if sender_info is None:
            sender_info = {}
        if post_info is None:
            post_info = {}
        if submit_time is None:
            submit_time = '100'

        url = self.__server_url + self.__api_url
        headers = {'User-Agent': self.user_agent,
                   'content-type': 'application/json; encoding=utf-8'}

        values = {
            'auth_key': self.__auth_key,
            'message': message,
            'sender_ip': sender_ip,
            'sender_email': sender_email,
            'sender_nickname': sender_nickname,
            'js_on': js_on,
            'agent': self.__agent,
            'post_info': post_info,
            'sender_info': sender_info,
            'submit_time': submit_time,
            'event_token': event_token
        }
        data = json.dumps(values, separators=(',', ':'))
        request = Request(url, data.encode(CleanTalk.ENCODING), headers)
        response = urlopen(request, timeout=self.__connection_timeout)
        response_bytes = response.read()
        response_str = response_bytes.decode(CleanTalk.ENCODING)
        response_parsed = json.loads(response_str)

        return response_parsed


def cleantalk_check_message(form_message,
                            form_sender_email,
                            form_sender_nickname='',
                            form_ip='',
                            form_event_token='',
                            form_submit_time='',
                            post_info=None,
                            sender_info=None):
    """
    API method "check_message" wrapper. Do check params and return result.
    :param str form_message: Required. Message field from HTML form.
    :param str form_sender_email: Required. Message field from HTML form.
    :param str form_sender_nickname: Message field from HTML form.
    :param str form_ip: Visitor's IP address
    :param str form_event_token: Bot detector event token field from HTML form.
    :param int form_submit_time: The time passed from page start to submit event.
    :param object post_info: Additional page info.
    :param object sender_info: Additional sender info.
    :return: object: {
        'result': '%1 if allowed, 0 if denied%',
        'comment': '%comment from cleantalk server%'
        }
    """

    # Init CleanTalk class object.

    ct = CleanTalk(
        auth_key=os.getenv('CLEANTALK_TEST_API_KEY'),
        method_name='check_message',
        server_url='https://moderate.cleantalk.org',
        api_url='/api2.0',
        connection_timeout=8,
        agent=None
    )

    # Run API request.

    ct_result = ct.request(
        message=form_message,
        sender_ip=form_ip,
        sender_email=form_sender_email,
        sender_nickname=form_sender_nickname,
        js_on=1,
        event_token=form_event_token,
        post_info=json.dumps(post_info),
        sender_info=json.dumps(sender_info),
        submit_time=form_submit_time
    )

    # Handle results.

    if ct_result['allow']:
        return {'result': 1, 'comment': ct_result['comment']}
    else:
        return {'result': 0, 'comment': ct_result['comment']}

Пример кода Django:

class ERegisterView(View):
    template_name = 'register.html'

    def get(self, request, *args, **kwargs):
        context = {}
        context.update(csrf(request))
        context['register_form'] = RegisterForm()
        return render(None, template_name=self.template_name, context=context)

    def post(self, request, *args, **kwargs):
        context = {}
        form = RegisterForm(request.POST)
        if form.is_valid():
            post_data = request.POST
            # run the check
            check_result = cleantalk_check_newuser(form_sender_email=post_data['email'],
                                                   form_sender_nickname=post_data['name'],
                                                   form_ip='199.1.2.3',
                                                   form_event_token=post_data['ct_bot_detector_event_token'])
            if not check_result['result']:
                context['is_spam'] = 1
                context['ct_comment'] = check_result['comment']

        return render(None, template_name=self.template_name, context=context)

Пример шаблона Django для использования в форме:

{% load django_bootstrap5 %}
{% bootstrap_css %}
{% bootstrap_javascript %}
{% bootstrap_messages %}

{% block page %}
    <h1>Registration</h1>
    <article>
    {% if register_form %}
        <p>Welcome!</p>
        <p>Please, register us via the form below.</p>
        <form id="register_form" action="{% url 'blog:register' %}" method="post">
            {% csrf_token %}
            {% bootstrap_form register_form %}
            <button type="submit">SEND</button>
        </form>
    {% elif is_spam %}
        <p>Seems to be spam: {{ct_comment}}</p>
    {% else %}
        <p>Success.</p>
    {% endif %}
    </article>
    {% comment %}
        Comment: Add Bot-detector JS script to send visitor's frontend params. This script do next:
        1. Collect frontend data and send them to the cloud directly from script.
        2. Adds the ct_bot_detector_event_token field to all the forms on the page. This token used to compare backend
            POST data and cloud data got from script.
    {% endcomment %}
    <script src="https://moderate.cleantalk.org/ct-bot-detector-wrapper.js" id="ct_bot_detector-js"></script>
{% endblock %}

NodeJS

Backend (Express.js)

1. Добавьте JavaScript код CleanTalk в блок <head>, чтобы он отображался на каждой странице: 

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

2. Установите CleanTalk:

npm install cleantalk

3. Добавьте CleanTalk в ваше приложение. 

4. Определите Ключ Доступа в вашей среде.

5. Соберите данные для отправки в облако CleanTalk. Посмотреть формат. 

6. Добавьте промежуточное CleanTalk к маршруту, который необходимо защитить от спама. 

const express = require('express');
const app = express();

// 1) Include the cleantalk middleware to youe app
const CleantalkMiddleware = require("cleantalk/src/middlewares/express");

// 2) Define the acces key in your environment
const auth_key = process.env.CLEANTALK_AUTH_KEY || null;

// 3)Collect the data to send to the cleantalk cloud.
const sender_info = {
    sender_email: 'body.sender_email',
    sender_nickname: 'body.sender_nickname',
    message: 'body.message',
};

// 4) Add the cleantalk middleware to the route need to be anti-spam protected
app.post('/form', CleantalkMiddleware(auth_key, 'message', sender_info), (req, res) => {
    if ( ! req.cleantalkDecision.isAllowed ) {
        res.send({message: req.cleantalkDecision.comment} );
    }
    res.send({});
});

C#

Команда CleanTalk будет благодарна вам за ваше возможное участие в реализации подробного примера для языка C#. Если вы хотите принять участие, свяжитесь с нами по адресу plugins@cleantalk.org.

Backend (.NET)

1. Загрузите приложение CleanTalk GitHub: https://github.com/CleanTalk/csharp-antispam
2. Добавьте ссылку на приложение cleantalk.csharp в вашем проекте.
3. Взгляните на наши тестовые примеры:

    public const string AuthKey = "auth key";

    [TestFixture]
    public class CheckMessageTests
    {
        private ICleantalk _cleantalk;

        [Test]
        public void NotSpamMessageTest()
        {
            var req1 = new CleantalkRequest(AuthKey)
            {
                Message = "This is a great storm!", //get this form the web form
                SenderInfo = new SenderInfo
                {
                    Refferrer = "https://www.bbc.co.uk/sport",
                    UserAgent = "Opera/9.80 (Windows NT 6.1; WOW64) Presto/2.12.388 Version/12.12"
                },
                SenderIp = "91.207.4.192",
                SenderEmail = "keanu8dh@gmail.com", /get this form the web form
                SenderNickname = "Mike", /get this form the web form
                //IsJsEnable = 1, redundant if use event_token
                EventToken = "f32f32f32f32f32f32f32f32f32f32a2",
                ///     To get this param:
                ///         1. add a script to the web-page: <script src="https://moderate.cleantalk.org/ct-bot-detector-wrapper.js" id="ct_bot_detector-js"></script>
                ///         2. parse the newly added hidden input on the web form, the name atrribute of input is "ct_bot_detector_event_token" 
                ///     @var string

                SubmitTime = 15
            };

            Debug.WriteLine("req1=" + WebHelper.JsonSerialize(req1));
            var res1 = _cleantalk.CheckNewuser(req1);
            Debug.WriteLine("res1=" + WebHelper.JsonSerialize(res1));
            Assert.IsNotNull(res1);
            Assert.IsNotNullOrEmpty(res1.Id);
            Assert.AreEqual(0, res1.IsInactive);
            Assert.IsTrue(res1.IsAllow.GetValueOrDefault());
            Assert.IsNotNullOrEmpty(res1.Comment);
        }
      }

Frontend (HTML)

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
    <script src="https://moderate.cleantalk.org/ct-bot-detector-wrapper.js" id="ct-bot-detector-js></script>
</head>
<body>
	<form method="post" action="chek_newuser.php">
    	<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="login">Message:</label>
    	<input type="text" name="message" id="message" /> <br />
    	<input type="submit" />
	</form>
</body>
</html>

GoLang

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"io/ioutil"
	"net/http"
	"strings"
)

var authKey string = "enter_your_key"
var configUrg string = "http://moderate.cleantalk.org/api2.0/"
var agent string = "golang-api"

type messageInputData struct {
	MethodName     string `json:"method_name"`
	AuthKey        string `json:"auth_key"`
	Agent          string `json:"agent"`
	SenderEmail    string `json:"sender_email"`
	SenderIp       string `json:"sender_ip"`
	SenderNickname string `json:"sender_nickname"`
	JsOn           uint   `json:"js_on"`
	SubmitTime     uint   `json:"submit_time"`
	AllHeaders     string `json:"all_headers"`
	Message        string `json:"message"`
	SenderInfo     string `json:"sender_info"`
	ResponseLang   string `json:"response_lang"`
	PostInfo       string `json:"post_info"`
	StoplistCheck  uint   `json:"stoplist_check"`
}

type MessageResultData struct {
	Version       string `json:"version"`
	Inactive      uint   `json:"inactive"`
	JsDisabled    uint   `json:"js_disabled"`
	Blacklisted   string `json:"blacklisted"`
	Comment       string `json:"comment"`
	Codes         string `json:"codes"`
	FastSubmit    uint   `json:"fast_submit"`
	Id            string `json:"id"`
	AccountStatus uint   `json:"account_status"`
	Allow         uint   `json:"allow"`
	StopQueue     uint   `json:"stop_queue"`
	Spam          uint   `json:"spam"`
}

func main() {
	inputData := messageInputData{
		MethodName:     "check_message",
		AuthKey:        authKey,
		Agent:          agent,
		SenderEmail:    "stop_email@example.com",
		SenderIp:       "192.168.0.1",
		SenderNickname: "testuser",
		JsOn:           1,
		SubmitTime:     5,
		Message:        "Test message",
	}

	resultData, err := CheckMessage(inputData)
	if err != nil {
		fmt.Println(err.Error())
		return
	}
	if resultData.Allow == 1 {
		fmt.Println(fmt.Sprintf("User allowed. Reason %s", resultData.Comment))
		return
	}
	fmt.Println(fmt.Sprintf("User forbidden. Reason %s", resultData.Comment))
}

func CheckMessage(inputData messageInputData) (MessageResultData, error) {
	inputDataBytes, err := json.Marshal(inputData)
	var resultData MessageResultData
	if err != nil {
		return resultData, err
	}
	var body io.Reader = strings.NewReader(string(inputDataBytes))
	req, err := http.NewRequest(http.MethodPost, configUrg, body)
	if err != nil {
		return resultData, err
	}
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		return resultData, err
	}
	defer resp.Body.Close()

	answer, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		return resultData, err
	}
	err = json.Unmarshal(answer, &resultData)
	return resultData, nil

Ссылки по теме

Опции, доступные при использовании с методом:

• Персональные списки CleanTalk позволяет блокировать нежелательных пользователей и разрешать пользователей, которые были ошибочно распознаны как спамеры.
• Опция Стоп-Слова позволяет блокировать комментарии и псевдонимы, содержащие любое слово из вашего списка стоп-слов.
• Опция блокировки стран позволяет блокировать все комментарии и регистрации из выбранных стран. 

Опции Стоп-Слова и блокировка по странам доступны после покупки нашего Дополнительного Пакета. Перейдите на страницу продления лицензии, чтобы увидеть подробности.