Внешний бот — документация разработчика

Существенно расширить возможности чата можно, если к чату подключить внешнего бота. Внешний бот — это программа или скрипт на стороннем сервере. Внешнему боту передаются фразы посетителей, отправленных на имя внешнего бота, а также он следит за входом и выходом посетителей. Внешней бот позволяет реализовать любую функциональность, на сколько хватит фантазии.

Важное замечание. Внешнему боту недоступны функции модерирования чата, т.к. ни один алгоритм не способен заменить человека.

Подключение внешнего бота

Чтобы подключить внешнего бота к чату необходимо активировать данную услугу в Личном Кабинете, при этом в интерфейсе администратора чата появится новый раздел "Внешний бот", где осуществляется его настройка. Для подключения внешнего бота необходимо указать три параметра сетевого соединения — полный адрес скрипта бота: хост, порт и путь к боту. Запросы на внешний бот посылаются по протоколу HTTP, поэтому внешний сервер должен быть настроен для работы с этим протоколом (подавляющее большинство серверов, предоставляемых хостинговыми компаниями, уже настроены для работы по протоколу HTTP). В качестве хоста может быть указано доменное имя либо IP-адрес сервера. Стандартным портом для протокола HTTP является 80-й порт, но если есть необходимость в использовании другого порта его можно изменить. И последний параметр подключения — путь к скрипту внешнего бота на сервере.

Для запуска внешнего бота необходимо в чат передать команду:

/bot имя_бота start EXTERNAL

API внешнего бота — обновление от 03.12.13

Реализовать внешнего бота можно на любом удобном языке программирования, необходимо только получить данные от сервера Сервиса. Данные на внешний сервер передаются методом POST через следующие переменные:

• event — событие, которое произвел пользователь;
• chatid — ID чата в системе August4u;
• userid — ID сессии пользователя;
• profile — номер профайла позователя, если он зарегистрирован;
• nick — ник пользовалеля;
• mess — сообщение пользователя;
• param — битовый набор флагов, определяющих свойства пользователя (пол, личка, невидимость и т.д. — см. шаблон).

Обновление от 02.02.14. Переменные admin, private, invisible и sex больше не передаются, вместо них используется переменная param, в которой содержатся свойства пользователя.

Всего внешний бот реагирует на три события от пользователя и на одно событие для зауска заданий по расписанию, соответственно, переменная event может принимать одно из значений:

• enter — пользователь вошел в чат;
• quit — пользователь покинул чат;
• mess — пользователь отправил сообщение;
• cmd — зауск задания по расписанию.

Для событий enter и quit не передаются сообщения, а для события quit также еще не передается и ник пользователя. Для события cmd имя команды передается в переменной mess.

Т.к. событие cmd инициируется не пользователем, то переменные profile, nick и param не содержат никаких значений, а переменная userid используется особым образом — в ней передается битовый набор комнат, в которых должно отображаться сообщение бота.

Результатом работы внешнего бота должна быть строка в кодировке utf-8, которая будет выведена в окно чата от имени бота.

Шаблон внешнего бота на PHP

<?
	define ('USER_SEX',		0x03);
	define ('USER_BIRTHDAY',	0x04);
	define ('USER_NEWBIE',		0x08);
	define ('USER_PRIVATE',		0x10);
	define ('USER_INVISIBLE',	0x20);
	define ('USER_ADMIN',		0x40);

	$Event     = $_POST ['event'];
	$ChatID    = intVal ($_POST ['chatid']);
	$UserID    = intVal ($_POST ['userid']);
	$Profile   = intVal ($_POST ['profile']);
	$Nick      = $_POST ['nick'];
	$Mess      = $_POST ['mess'];
	$Param     = intVal ($_POST ['param']);
	$Sex       = $Param & USER_SEX;		//  получить пол пользователя: 0 = не определено, 1 = мужской, 2 = женский
	$Birthday  = $Param & USER_BIRTHDAY;	//  у пользователя день рождения
	$Newbie    = $Param & USER_NEWBIE;	//  пользователь зашел в чат с регистрацией первый раз
	$Private   = $Param & USER_PRIVATE;	//  пользователь отправил сообщение в личку
	$Invisible = $Param & USER_INVISIBLE;	//  пользователь находится в невидимках
	$Admin     = $Param & USER_ADMIN;	//  пользователь является администратором

	switch ($Event) {
		case 'enter':
			//  обработчик входа пользователя в чат
			...
			break;
		case 'quit':
			//  обработчик выхода пользователя из чата
			...
			break;
		case 'mess':
			//  обработчик сообщения от пользователя
			...
			break;
	}
?>

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

<?
	define ('USER_SEX',		0x03);
	define ('USER_BIRTHDAY',	0x04);
	define ('USER_NEWBIE',		0x08);
	define ('USER_PRIVATE',		0x10);
	define ('USER_INVISIBLE',	0x20);
	define ('USER_ADMIN',		0x40);

	$Event     = $_POST ['event'];
	$ChatID    = intVal ($_POST ['chatid']);
	$UserID    = intVal ($_POST ['userid']);
	$Profile   = intVal ($_POST ['profile']);
	$Nick      = $_POST ['nick'];
	$Mess      = $_POST ['mess'];
	$Param     = intVal ($_POST ['param']);

	switch ($Event) {
		case 'enter':
			break;
		case 'quit':
			break;
		case 'mess':
			break;
		case 'cmd':
			//  имя задания в настройках бота anekdot
			if ($_POST ['mess'] == 'anekdot') {
				include "include/anekdot.inc.php";
				$a = get_anekdot ();
				print "<div class=anekdot>$a</div>";
				exit;
			}
			break;
	}
?>

Для этого примера необходимо скачать модуль, получающий анекдот с внешнего сайта, и разместить его в каталоге include.

• zip-aрхив /// скачан: 55 раз(а), сегодня: 0
• bz2-aрхив /// скачан: 48 раз(а), сегодня: 0