Nextcloud Talk

Подключение PRX к Nextcloud Talk через OCS API и доставку сообщений на основе вебхуков для самохостингового командного обмена сообщениями.

Предварительные требования

• Экземпляр Nextcloud (рекомендуется версия 25 или новее) с включённым приложением Talk
• Токен бот-приложения для аутентификации OCS API
• Настроенные вебхуки для доставки входящих сообщений

Быстрая настройка

1. Создание токена бот-приложения

В Nextcloud сгенерируйте пароль приложения:

1. Перейдите в Настройки > Безопасность > Устройства и сессии
2. Создайте новый пароль приложения с описательным именем (например, «PRX Bot»)
3. Скопируйте сгенерированный токен

Альтернативно, для Nextcloud Talk Bot API (Nextcloud 27+):

1. Используйте occ для регистрации бота: php occ talk:bot:setup "PRX" <secret> <webhook-url>

2. Конфигурация

[channels_config.nextcloud_talk]
base_url = "https://cloud.example.com"
app_token = "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
allowed_users = ["admin", "alice"]

3. Настройка вебхуков

Настройте бота Nextcloud Talk для отправки вебхук-событий на эндпоинт шлюза PRX:

POST https://your-prx-domain.com/nextcloud-talk

4. Проверка

prx channel doctor nextcloud_talk

Справочник конфигурации

Поле	Тип	По умолчанию	Описание
base_url	String	обязательный	Базовый URL Nextcloud (например, "https://cloud.example.com")
app_token	String	обязательный	Токен бот-приложения для bearer-аутентификации OCS API
webhook_secret	String	null	Общий секрет для проверки подписи вебхуков HMAC-SHA256. Также может быть задан через переменную окружения ZEROCLAW_NEXTCLOUD_TALK_WEBHOOK_SECRET
allowed_users	[String]	[]	Разрешённые ID акторов Nextcloud. Пусто = запрещено всем. "*" = разрешить всем

Возможности

• Доставка через вебхуки — получение сообщений через HTTP-вебхук push от Nextcloud Talk
• Ответы через OCS API — отправка ответов через OCS REST API Nextcloud Talk
• Верификация HMAC-SHA256 — опциональная проверка подписи вебхуков с webhook_secret
• Несколько форматов данных — поддержка как устаревшего/пользовательского формата, так и формата Activity Streams 2.0 (вебхуки бота Nextcloud Talk)
• Самохостинг — работает с любым экземпляром Nextcloud, сохраняя все данные на вашей инфраструктуре

Ограничения

• Требуется публично доступный HTTPS-эндпоинт для доставки вебхуков (или обратный прокси)
• Nextcloud Talk bot API доступен начиная с Nextcloud 27+; более ранние версии требуют пользовательской настройки вебхуков
• Бот должен быть зарегистрирован в комнате Talk для получения сообщений
• Обработка файловых и медиавложений в настоящее время не поддерживается
• Временные метки вебхуков в миллисекундах автоматически нормализуются в секунды

Устранение неполадок

Вебхук-события не получаются

• Проверьте, что URL вебхука публично доступен и указывает на https://your-domain/nextcloud-talk
• Убедитесь, что бот зарегистрирован в комнате Talk
• Проверьте логи сервера Nextcloud на наличие ошибок доставки вебхуков

Проверка подписи не проходит

• Убедитесь, что webhook_secret совпадает с секретом, использованным при регистрации бота
• Секрет может быть задан через конфигурацию или переменную окружения ZEROCLAW_NEXTCLOUD_TALK_WEBHOOK_SECRET

Ответы не отправляются

• Проверьте корректность base_url и его доступность с сервера PRX
• Убедитесь, что app_token имеет разрешение на отправку сообщений в комнату
• Проверьте ответ OCS API на наличие ошибок аутентификации или разрешений