2 часа назад 6 секунд назад

Полная инструкция: создание бота Nextcloud Talk 📚

от Пес 2 часа назад6 секунд назад

Время чтения: 8 мин.

232просмота

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

Оглавление

Подготовка
Создание пользователя-бота
Создание токена приложения
Создание скрипта бота
Установка и настройка бота
Подключение бота к комнате
Управление ботом
Добавление новых команд
Частые проблемы и решения
Полезные команды для отладки
Быстрый старт (чек-лист)
Полезные ссылки и инфа

1. Подготовка

Проверка версии Nextcloud и Talk

# Проверяем версию Talk
sudo -u apache php /var/www/html/nextcloud/occ app:list | grep spreed

# Проверяем, есть ли поддержка ботов
sudo -u apache php /var/www/html/nextcloud/occ talk:bot:list --output=json_pretty

Создаём папку для бота

# Создаём папку
mkdir -p /var/www/html/nextcloud/talkbot

# Создаём папку для логов
mkdir -p /var/www/html/nextcloud/talkbot/logs

# Даём права
chown -R apache:apache /var/www/html/nextcloud/talkbot/
chmod -R 755 /var/www/html/nextcloud/talkbot/
chmod 777 /var/www/html/nextcloud/talkbot/logs/  # Временно, для теста, после отладки выставить 755

2. Создание пользователя-бота

Создаем пользователя (например «user_bot»)

# Вариант 1: с вводом пароля
sudo -u apache php /var/www/html/nextcloud/occ user:add user_bot

# Вариант 2: с паролем из переменной
export OC_PASS="Bot_Password_1234"
sudo -u apache php /var/www/html/nextcloud/occ user:add user_bot --display-name="Тестовый Бот" --password-from-env

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

sudo -u apache php /var/www/html/nextcloud/occ user:list | grep user_bot

3. Создание токена приложения Nextcloud

Далее нужно зайти в Nextcloud под пользователем «user_bot» для создания токена приложения для работы бота.

Войти в Nextcloud как user_bot
Нажми на аватарку → Личные настройки → Безопасность
Прокрути вниз до «Активные устройства и сеансы»
Вводим название приложения, например «Bot Talk» и жмем «Создать пароль приложения«
Записываем сгенерированный токен отдельно, после закрытия окна он будет скрыт и недоступен.

Проверяем токен

curl -X GET "https://nextcloud.com/ocs/v2.php/cloud/user" \
  -H "OCS-APIRequest: true" \
  -H "Authorization: Bearer <ТВОЙ_ТОКЕН_ПРИЛОЖЕНИЯ_BOT_TALK>"

Ожидаемый ответ: <status>ok</status> и данные пользователя.

4. Код бота Nextcloud Talk

Создаём файл для бота Nextcloud Talk — /var/www/html/nextcloud/talkbot/bot.php

<?php
$secret = '<ЭТОТ_СЕКРЕТНЫЙ_КОД_ДОЛЖЕН_БЫТЬ_МИНИМУМ_40_СИМВОЛОВ>';
$logDir = '/var/www/html/nextcloud/talkbot/logs';
$logFile = $logDir . '/bot.log';

if (!is_dir($logDir)) mkdir($logDir, 0755, true);

// Пишем ВСЁ, что приходит
file_put_contents($logFile, "\n========== " . date('Y-m-d H:i:s') . " ==========\n", FILE_APPEND);
file_put_contents($logFile, "METHOD: " . $_SERVER['REQUEST_METHOD'] . "\n", FILE_APPEND);

$body = file_get_contents('php://input');
file_put_contents($logFile, "BODY: " . $body . "\n", FILE_APPEND);

// Проверка метода
if ($_SERVER['REQUEST_METHOD'] !== 'POST') { 
    file_put_contents($logFile, "НЕ POST\n", FILE_APPEND);
    http_response_code(400); 
    exit; 
}

// Проверка подписи
$random = $_SERVER['HTTP_X_NEXTCLOUD_TALK_RANDOM'] ?? '';
$digest = hash_hmac('sha256', $random . $body, $secret);

if (!hash_equals($digest, strtolower($_SERVER['HTTP_X_NEXTCLOUD_TALK_SIGNATURE'] ?? ''))) {
    file_put_contents($logFile, "❌ Ошибка подписи!\n", FILE_APPEND);
    http_response_code(403);
    exit;
}

file_put_contents($logFile, "✅ Подпись верна\n", FILE_APPEND);

$data = json_decode($body, true);

// Проверяем, что это сообщение
if ($data && isset($data['type']) && $data['type'] === 'Create' && 
    isset($data['object']['mediaType']) && $data['object']['mediaType'] === 'text/markdown') {
    
    $messageData = json_decode($data['object']['content'], true);
    $text = $messageData['message'] ?? '';
    $user = $data['actor']['name'] ?? 'Аноним';
    $roomToken = $data['target']['id'] ?? '';
    
    file_put_contents($logFile, "📩 Сообщение от $user: $text (токен: $roomToken)\n", FILE_APPEND);
    
    // ============================================
    // 👇 СЮДА ВСТАВЛЯЙ ВСЕ НОВЫЕ КОМАНДЫ
    // ============================================
    
    // Обработка команды /help
    if (strpos($text, '/help') === 0) {
        $reply = "📚 Доступные команды:\n/test - тестовый ответ\n/help - справка\n/time - текущее время";
    }
    // Обработка команды /time
    elseif (strpos($text, '/time') === 0) {
        $reply = "🕐 Текущее время: " . date('H:i:s');
    }
    // Обработка команды /test
    elseif (strpos($text, '/test') === 0) {
        $reply = "🤖 Привет, $user! Ты написал: " . substr($text, 5);
    }
    // Если команда не распознана
    else {
        // Ничего не отвечаем (или можно добавить ответ по умолчанию)
        $reply = "❌ я не понимаю команду: $text";
    }
    
    // ============================================
    // 👆 КОНЕЦ БЛОКА С КОМАНДАМИ
    // ============================================
    
    // Отправляем ответ, если команда была распознана
    if ($reply) {
        $apiUrl = "https://nextcloud.com/ocs/v2.php/apps/spreed/api/v1/chat/$roomToken";
        $appToken = '<ТВОЙ_ТОКЕН_ПРИЛОЖЕНИЯ_BOT_TALK>';
        
        file_put_contents($logFile, "URL: $apiUrl\n", FILE_APPEND);
        
        $ch = curl_init($apiUrl);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['message' => $reply]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Content-Type: application/json',
            'OCS-APIRequest: true',
            'Authorization: Bearer ' . $appToken
        ]);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        file_put_contents($logFile, "📤 HTTP Code: $httpCode\n", FILE_APPEND);
        file_put_contents($logFile, "📤 Response: $response\n", FILE_APPEND);
    }
}

http_response_code(200);
echo 'OK';

Важно! В коде бота Nextcloud Talk (bot.php) используется curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);. Это отключает проверку SSL-сертификата. Стоит добавить сноску, что для продакшена так делать небезопасно, и лучше указать путь до файла с сертификатами (CURLOPT_CAINFO).

Вместо того чтобы хранить секретный ключ ($secret) и токен приложения ($appToken) прямо в коде bot.php, можно вынести их в переменные окружения или отдельный конфиг-файл. Это безопаснее.

Проверяем создание файла

# Проверяем права
chown apache:apache /var/www/html/nextcloud/talkbot/bot.php
chmod 755 /var/www/html/nextcloud/talkbot/bot.php

# Проверяем доступность
curl -I https://nextcloud.com/talkbot/bot.php
# Должен быть ответ 400 Bad Request (это нормально)

5. Установка и настройка бота Nextcloud Talk

Устанавливаем бота

sudo -u apache php /var/www/html/nextcloud/occ talk:bot:install \
  "TestBot" \
  "<ЭТОТ_СЕКРЕТНЫЙ_КОД_ДОЛЖЕН_БЫТЬ_ДЛИННЫМ_МИНИМУМ_40_СИМВОЛОВ>" \
  "https://nextcloud.com/talkbot/bot.php" \
  --feature webhook

Мы используем --feature webhook. Стоит добавить краткое пояснение:

webhook — бот отвечает на любое сообщение в комнате;
response — бот отвечает только когда его упомянут (например, @TestBot /help).

Это важно, потому что поведение сильно отличается.

Проверяем установку

sudo -u apache php /var/www/html/nextcloud/occ talk:bot:list --output=json_pretty

Ожидаемый вывод:

[
    {
        "id": 1,
        "name": "TestBot",
        "description": "",
        "error_count": 0,
        "state": 1,
        "features": "webhook"
    }
]

Чтобы вывести общий список всех ботов нужна команда:

sudo -u apache php /var/www/html/nextcloud/occ talk:bot:list

Пример отображения списка:

Полная инструкция: создание бота Nextcloud Talk 📚

6. Подключение бота к комнате/обсуждению и настройка бота

В вебинтерфейсе создаем комнату/обсуждение, добавляем пользователя-бота в участники.

Способ 1: Через OCC (универсальный)

# Подключаем бота к комнате по её токену
sudo -u apache php /var/www/html/nextcloud/occ talk:bot:setup <ID_бота> <токен_комнаты>

<токен_комнаты> — это часть ссылки на комнату/обсуждение

Пример:

# Подключаем бота к комнате по её токену
sudo -u apache php /var/www/html/nextcloud/occ talk:bot:setup 1 сiq12v6i

Способ 2: Если забыл ID бота

# Сначала узнаём ID
sudo -u apache php /var/www/html/nextcloud/occ talk:bot:list --output=json_pretty

# Затем подключаем
sudo -u apache php /var/www/html/nextcloud/occ talk:bot:setup <ID_бота> <токен_комнаты>

Способ 3: Сначала добавить пользователя в комнату

# Добавляем пользователя-бота в комнату
sudo -u apache php /var/www/html/nextcloud/occ talk:room:add <токен_комнаты> --user user_bot

7. Управление ботом

Список всех команд для управления ботом:

Команда	Описание
`talk:bot:list`	Показать всех установленных ботов
`talk:bot:list <токен_комнаты>`	Показать ботов в конкретной комнате
`talk:bot:setup <ID> <токен>`	Добавить бота в комнату
`talk:bot:remove <ID> <токен>`	Удалить бота из комнаты
`talk:bot:state <ID> <0/1>`	Отключить (0) или включить (1) бота
`talk:bot:uninstall <ID>`	Полностью удалить бота

Примеры:

# Включить бота
sudo -u apache php /var/www/html/nextcloud/occ talk:bot:state 9 1

# Отключить бота
sudo -u apache php /var/www/html/nextcloud/occ talk:bot:state 9 0

# Удалить бота из комнаты
sudo -u apache php /var/www/html/nextcloud/occ talk:bot:remove 9 сiq12v6i

# Полностью удалить бота
sudo -u apache php /var/www/html/nextcloud/occ talk:bot:uninstall 9

8. Добавление новых команд

Шаблон для добавления новой команды

В скрипте bot.php в блоке обработки команд добавь новый elseif:

// Команда /mycommand
elseif (strpos($text, '/mycommand') === 0) {
    $reply = "Мой ответ на команду!";
}

Пример с дополнительной логикой:

// Команда /echo [текст] - повторяет текст
elseif (strpos($text, '/echo') === 0) {
    $echoText = substr($text, 6); // Убираем "/echo "
    $reply = "🔊 Ты сказал: $echoText";
}

// Команда /calc 2+2 - калькулятор
elseif (strpos($text, '/calc') === 0) {
    $expression = substr($text, 6);
    try {
        $result = eval("return $expression;");
        $reply = "📊 $expression = $result";
    } catch (Throwable $e) {
        $reply = "❌ Ошибка в выражении";
    }
}

9. Частые проблемы и решения

❌ Проблема: Бот не отвечает

✅ Решение:

# 1. Проверь лог
cat /var/www/html/nextcloud/talkbot/logs/bot.log

# 2. Проверь права на файл/папку
ls -la /var/www/html/nextcloud/talkbot/bot.php
ls -la /var/www/html/nextcloud/talkbot/logs/

# 3. Перезапусти PHP-FPM
sudo systemctl restart php-fpm

# 4. Проверь, что бот включён
sudo -u apache php /var/www/html/nextcloud/occ talk:bot:list --output=json_pretty

❌ Проблема: Ошибка 403 — неверная подпись

✅ Решение:

# Проверь совпадение секрета в скрипте и при установке
grep "secret" /var/www/html/nextcloud/talkbot/bot.php

❌ Проблема: Ошибка 404 при отправке сообщения

✅ Решение:

# Проверь, что пользователь-бот есть в комнате
sudo -u apache php /var/www/html/nextcloud/occ talk:room:add <токен_комнаты> --user bot_user

# Проверь токен приложения
curl -X GET "https://nextcloud.com/ocs/v2.php/cloud/user" \
  -H "OCS-APIRequest: true" \
  -H "Authorization: Bearer <ТОКЕН>"

❌ Проблема: Бот не видит новых команд

✅ Решение:

# Очисти кеш OPcache
sudo systemctl restart php-fpm

# Или если используешь Apache
sudo systemctl restart httpd

# Проверь, что файл обновился
head -100 /var/www/html/nextcloud/talkbot/bot.php | grep "твоя_команда"

10. Полезные команды для отладки

Проверка логов:

# Лог бота
tail -f /var/www/html/nextcloud/talkbot/logs/bot.log

# Лог Nextcloud
tail -f /var/www/html/nextcloud/data/nextcloud.log

# Лог веб-сервера
tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log

Проверка API напрямую:

# Отправить сообщение от бота вручную
curl -X POST "https://nextcloud.com/ocs/v2.php/apps/spreed/api/v1/chat/<токен_комнаты>" \
  -H "OCS-APIRequest: true" \
  -H "Authorization: Bearer <ТОКЕН_БОТА>" \
  -H "Content-Type: application/json" \
  -d '{"message":"Тестовое сообщение"}'

Проверка комнаты:

# Найти ID комнаты по токену
sudo -u apache php /var/www/html/nextcloud/occ db:query "SELECT id, token, name FROM oc_talk_rooms WHERE token='<токен_комнаты>';"

11. Быстрый старт (чек-лист)

Если нужно быстро создать нового бота:

# 1. Установить бота
sudo -u apache php /var/www/html/nextcloud/occ talk:bot:install \
  "НазваниеБота" \
  "ТВОЙ_СЕКРЕТ" \
  "https://nextcloud.com/talkbot/bot.php" \
  --feature webhook

# 2. Запомнить ID
sudo -u apache php /var/www/html/nextcloud/occ talk:bot:list --output=json_pretty

# 3. Подключить к комнате
sudo -u apache php /var/www/html/nextcloud/occ talk:bot:setup <ID> <токен_комнаты>

12. Полезные ссылки и инфа

Официальная документация: https://nextcloud-talk.readthedocs.io/en/stable/bots/
API Reference: https://nextcloud-talk.readthedocs.io/en/latest/global/
Файлы бота: /var/www/html/nextcloud/talkbot/
Логи бота: /var/www/html/nextcloud/talkbot/logs/bot.log

В статье везде используется путь /var/www/html/nextcloud/. Убедитесь, что это актуально для вашей установки. Если Nextcloud стоит в другом месте (например, /var/www/nextcloud), стоит сделать на это акцент.