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

Введение

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

Код sql пакета - maxbot.

См. также Интеграция Falcon Space с Max мессенджером

Страница maxbot

Каждая команда имеет свою процедуру, выполняющую отклик на команду. 

Команда может в точности соответствовать поле команда, либо быть начальным значением вводимой команды (в этом случае необходимо установить параметр Сравнение первых N символов). 

Меню

В боте есть предустановленные команды: 

Меню - устанавливает меню на основе команд и их настроек (Меню роли, Строка в меню, Порядок). 

Роль меню - по умолчанию all (показывается всем). Если указать роли сайта через запятую, то этот пункт в меню будет выводиться только тем, у кого ТГ логин соотнесен с пользовалем системы в соответствующей роли.

Помощь -  либо указывает общий текст помощи, либо если указана команда через пробел, то выводит по ней подсказку (она задается в поле Подсказка в help). 

Эти команды действувуют, если админ не создал свои команды с теми же названиями. 

В меню может быть до 10 строк. Порядок определяет сотрировку элементов внутри строки.

Если вы хотите использовать емодзи или смайлики, то необходимо скопировать (Ctrl+C , Ctrl +V) из телеграм или Max и вставить в название команды.

Блокировка пользователей 

Есть черный список пользователей, где можно указать либо telegram логин или chatID. Если пользователь попал в черный список, то на любую команду ему идет сообщение, что он заблокирован (текст управляется через настройку Отклик бота: Сообщение о блокировке пользователя - maxBlockUserResponse).

Выполнение команд

Каждая команда это отдельная процедура (название процедуры определяется кодом, который назначается при создании команды и не меняется), которая выдает три SELECT 

• SELECT 1 - внешнее действие по вызову API request для отправки запроса в Max

По каждой команде ведется лог обращений и можно посмотреть какой был запрос и отклик + время на обработку. 

При нажатии на max идет переход к общей переписке этого пользователя с ботом. 

Каждую команду можно отключать (переключатель Отключено). Отключенные команды исключаются из меню и недоступны для пользователей.

Если команда не найдена, то выдается сообщение пользователю (управляется через настройку maxNotFoundCommand).

Лог ошибок бота

Лог ошибок бота ведется отдельно от общих ошибок сайта. 

Страница вывода переписки /maxchats

На странице можно выбрать max и просмотреть лог переписки, а также что-то написать от имени бота пользователю Max.

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

Многоступенчатые команды бота

Многоступенчатая команда - это запуск некой команды с предполагаемым последующим запросом дополнительных данных (т.е. дальнейший ввод пользователя считается не командой, а дополнительными данными к текущей команде). 

Примеры подобных команд:

• Заполнение анкеты 
• Заявка на заказ некой услуги
• Регистрация на сайте (создание личного кабинета через Телеграм)
          

Если вам необходимо пошагово запросить информацию у пользователя в рамках одной команды, то используем параметры step (в parameters) и выходной параметр nextStep. 

CREATE PROCEDURE [dbo].[max_multicommand1_command]
  @command nvarchar(max),
  @max nvarchar(256),
    @chatID bigint,
    @parameters ExtendedDictionaryParameter readonly,
    @result bit output,
    @msg nvarchar(max) output,
    @nextStep nvarchar(128) output
AS
BEGIN
    DECLARE @messageID BIGINT = (SELECT TOP 1 TRY_CAST(value2 AS BIGINT) FROM @parameters WHERE [key] = 'messageID');
    DECLARE @currentStep NVARCHAR(128) = (SELECT TOP 1 value2 FROM @parameters WHERE [key] = 'currentStep');
    DECLARE @commandData NVARCHAR(MAX) = (SELECT TOP 1 value2 FROM @parameters WHERE [key] = 'commandData');

    SET @result = 1;

    IF @currentStep = ''
    BEGIN
        -- первый шаг
        SET @msg = 'Укажите имя:';
        SET @nextStep = 's2';
    END
    ELSE IF @currentStep = 's2'
    BEGIN
        -- второй шаг
        SET @msg = 'Укажите фамилию:';
        SET @nextStep = 's3';
    END
    ELSE IF @currentStep = 's3'
    BEGIN
        -- третий шаг
        DECLARE @name NVARCHAR(255) = JSON_VALUE(@commandData, '$.s2');
        DECLARE @surname NVARCHAR(255) = JSON_VALUE(@commandData, '$.s3');
        
        SET @msg = 'Ваша заявка принята!' + CHAR(10) + CHAR(10) +
                           'Имя: ' + ISNULL(@name, 'не указано') + CHAR(10) +
                           'Фамилия: ' + ISNULL(@surname, 'не указано');
        SET @nextStep = ''; 
    END
    ELSE
    BEGIN
        -- Если вдруг попали в неожиданный шаг
        SET @msg = 'Заказ завершён.';
        SET @nextStep = '';
    END

    -- формируем JSON для отправки
    DECLARE @optionsJson NVARCHAR(MAX) = (
        SELECT 
            @chatID AS chatID,
            @max AS userID,
            @msg AS text,
            'html' AS format,
            @messageID AS replyMessageID
        FOR JSON PATH, WITHOUT_ARRAY_WRAPPER
    );
    
    SELECT 
        'apirequest' AS [type],
        'maxSendMessage' AS code,
        'options' AS p1_name,
        @optionsJson AS p1_value;
    
    RETURN;
END

Пояснение: 

1. Если step = '' - это первый шаг в команде.
2. Если из процедуры вернули непустой nextStep, то это значит что команда многоступенчатая и следующий ввод пользователя считает продолжением этой команды (и будет передан step, равный значению текущего nextStep). 
3. Если из процедуры вернули пустой nextStep, то это либо была простая команда (с 1 шагом), либо это было завершение многоступенчатой команды. В этом случае бот будет ожидать новой команды при следующем вводе пользователя. 
4. Данные по шагам и результаты ввода хранятся в max_settings - currentCommand, currentCommandStep и currentCommandData. Данные в data хранятся в виде step1=XXX~~step2=YYY...

Привязка пользователя Max к аккаунту на сайте

Используется форма addMaxMessenger.

Привязка идет по полям as_users: maxCode и maxChatID - пользователь переходит в Max и выполняет команду Привязать {maxCode} (генерируется случайно).

Если код верный, то у пользователя прописывается настройка maxChatID.

Команда Привязать выглядит следующим образом:

CREATE PROCEDURE [dbo].[max_privyazat_command]
  @command nvarchar(max),
  @max nvarchar(256),
    @chatID bigint,
    @parameters ExtendedDictionaryParameter readonly,
    @result bit output,
    @msg nvarchar(max) output,
    @nextStep nvarchar(128) output
AS
BEGIN
    set @nextStep=''
    declare @messageID bigint = (select top 1 try_cast(value2 as bigint) from @parameters where [key]='messageID')

    set @result = 1
    
    declare @commandText nvarchar(max) = isnull((select value2 from @parameters where [Key] = 'commandText'), '')
    declare @maxCode nvarchar(max) = rtrim( ltrim(replace(@commandText, 'привязать ','')))  

    declare @userID int = (select id from as_users where maxCode = @maxCode and isnull(maxCode, '')>0 and (maxChatID is null or maxChatID = 0))
    if(@userID>0) begin 
        set @msg = 'Ваш аккаунт привязан к логину '+(select username from as_users where id = @userID)+' на сайте'
        update as_users set maxChatID = @chatID where id = @userID
    end else begin 
        set @msg = 'Неверно введен код привязки пользователя'
    end 
    declare  @optionsJson nvarchar(max) = (SELECT
                @chatID  chatID,
                NULL userID,
                @msg text,
                'html'  format,
                @messageID AS replyMessageID,
                NULL AS logID
    FOR JSON PATH, WITHOUT_ARRAY_WRAPPER)

    --SELECT 1
    SELECT 'apirequest' type,  'maxSendMessage' AS code,  'options' AS p1_name, @optionsJson AS p1_value
END

После привязки можно отправлять уведомления пользователю через коллбек после уведомлений (вызов внешнего действия apirequest для отправки в Max по chatID).