Входящие вебхуки MAX в Joomla

WT Max библиотека для интеграции с Joomla - Документация
Категория: Библиотеки

Настройка подписки MAX, проверка секрета и разрешённых чатов, обработка входящих событий через типизированный WebhookEvent в Joomla.

Настройка подписки

  1. Включите и настройте System - WT Max, сохраните токен бота.
  2. На вкладке «Вебхуки» включите входящие вебхуки. Пустое поле секрета заполняется автоматически при открытии формы.
  3. Сохраните параметры и повторно откройте форму. Для подписки должны использоваться уже сохранённые настройки.
  4. При необходимости заполните «Разрешённые chat_id»: каждый ID на отдельной строке. Для подписки можно выбрать message_created и message_callback.
  5. Нажмите кнопку создания подписки. Проверьте результат и список подписок текущего сайта.

Webhook URL формируется плагином автоматически:

https://example.com/index.php?option=com_ajax&plugin=wtmax&group=system&format=raw&action=webhook&secret=YOUR_WEBHOOK_SECRET

YOUR_WEBHOOK_SECRET — условное обозначение. Используйте URL из настроек своего сайта. Секрет вебхука и токен бота — разные значения. После смены домена или секрета сохраните параметры и пересоздайте подписку с актуальными данными.

По требованиям MAX к подпискам, обработчик должен быть доступен по HTTPS на порту 443 с доверенным сертификатом и полной цепочкой. Он должен отвечать HTTP 200 в пределах 30 секунд. Тяжёлую обработку лучше передавать в очередь.

Что проверяет плагин

До вызова пользовательских обработчиков WT Max проверяет включение вебхуков, непустой сохранённый секрет, его совпадение одновременно с query-параметром secret и заголовком X-Max-Bot-Api-Secret, а затем непустое корректное JSON-тело.

Пустой список разрешённых чатов допускает все запросы, прошедшие эти проверки. При заполненном списке плагин извлекает chat_id из получателя сообщения и пропускает только совпавшие ID. События без такого ID также игнорируются. Это существенно для событий, не содержащих объект сообщения.

Если чат не разрешён, событие Joomla не вызывается и обработчик возвращает ignored. После успешных проверок вызывается onWtmaxIncomingWebhook для плагинов групп system и wtmax.

Пример обработчика Joomla

Ниже класс расширения плагина, а не полный установочный пакет. Для своего плагина добавьте манифест и регистрацию сервиса Joomla, установите и включите его.

<?php
declare(strict_types=1);

namespace Joomla\Plugin\System\Example\Extension;

use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\Event\SubscriberInterface;
use Webtolk\Wtmax\Event\WebhookEvent;

defined('_JEXEC') or die;

final class Example extends CMSPlugin implements SubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return ['onWtmaxIncomingWebhook' => 'handleWtmaxWebhook'];
    }

    public function handleWtmaxWebhook(WebhookEvent $event): void
    {
        if ($event->getUpdateType() !== 'message_created') {
            return;
        }

        $message = $event->getMessage();
        $chatId = $event->getChatId();

        if ($message === null || $chatId === null) {
            return;
        }

        $text = $message->getBody()?->getText() ?? '';
        $data = $event->getData();

        // Здесь разместите логику вашего расширения.
        // Повторная доставка одного события не должна повторять бизнес-операцию.
    }
}

Контракт WebhookEvent

  • getData(): array — исходный декодированный JSON.
  • getUpdate(): ?Webtolk\Max\Entity\Update — типизированный объект SDK.
  • getUpdateType(): ?string — тип обновления.
  • getMessage(): ?Webtolk\Max\Entity\Message — сообщение, если оно есть в событии.
  • getChatId(): ?int — ID, определённый системным плагином.
  • getAllowedChatIds(): array и isAllowedChat(): bool — сведения о проверке разрешённых чатов.

Для message_callback сначала проверяйте тип события и читайте соответствующие данные из getData() или getUpdate(); сообщение может отсутствовать. MAX может повторять доставку, поэтому обработчики должны защищать бизнес-операции от дублирования.

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

Список показывает подписки бота и выделяет подписки текущего сайта. Из формы WT Max удаляются только выбранные подписки текущего сайта. Отключение приёма в плагине и удаление подписки в MAX — отдельные действия.

Другие разделы WT Max

Расширения Joomla WebTolk

113 Всего расширений
12 Категорий
588 Выпущено версий
949240 Всего скачиваний