alisa

Bot for Yandex.Alice

Pre-setting

Morphological dictionary

The bot uses first-form word conversion to more accurately recognize the user's query. To work correctly, you must have a dictionary of words in the desired language. This set is suitable for the Russian language. It is mandatory to specify the path to the dictionary.

alisa('NAME'); //Такой используется по умолчанию $bot->setDictionaryPath($_SERVER['DOCUMENT_ROOT'] . '/dicts/');">

 $ bot = new alisa ( ' NAME ' );                         
//Такой используется по умолчанию
$ bot -> setDictionaryPath ( $ _SERVER [ ' DOCUMENT_ROOT ' ] . ' /dicts/ ' );

Session storage directory

Sessions – *.json file in which all service information is stored within the essence of one dialogue. You must specify the path to the directory in which the data will be stored.

alisa('NAME'); //Такой используется по умолчанию $bot->setDictionaryPath($_SERVER['DOCUMENT_ROOT'] . '/sessions/');">

 $ bot = new alisa ( ' NAME ' );                         
//Такой используется по умолчанию
$ bot -> setDictionaryPath ( $ _SERVER [ ' DOCUMENT_ROOT ' ] . ' /sessions/ ' );

Work protocol

alisa('myawesomebot'); //Создаем триггер, в качестве аргумента строка с уникальным именем $helloTrigger = new Trigger('HELLO'); //Привязываем к триггеру токены – в данном случае в одну группу. //Токены – ключевые слова, объединенные в группы $helloTrigger->linkTokens(['привет','здравствуйте','приветсвую']); $bayTrigger = new Trigger('bay'); $bayTrigger->linkTokens(['пока','до свидания','прощай']); //Привязываем триггеры боту $bot->addTrigger($helloTrigger,$bayTrigger); //Отправляем ответ, если распознан $helloTrigger $bot->sendResponse($helloTrigger,static function(){ //$answer - экземпляр отправляемого ответа $answer = new Response(); $answer->addText('Привет!'); $answer->addText('Доброго времени суток!'); //обязательно возвращаем объект Response return $answer; ); //Отправляем ответ, если распознан $bayTrigger $bot->sendResponse($bayTrigger,static function(){ $answer = new Response(); $answer->addText('Прошай!'); $answer->addText('Всего доброго'); //обязательно возвращаем объект Response return $answer; );">

 //Создаем бота. Аргумент – название навыка
$ bot = new alisa ( ' myawesomebot ' );

//Создаем триггер, в качестве аргумента строка с уникальным именем
$ helloTrigger = new Trigger ( ' HELLO ' );

//Привязываем к триггеру токены – в данном случае в одну группу.
//Токены – ключевые слова, объединенные в группы
$ helloTrigger -> linkTokens ([ ' привет ' , ' здравствуйте ' , ' приветсвую ' ]);


$ bayTrigger = new Trigger ( ' bay ' );
$ bayTrigger -> linkTokens ([ ' пока ' , ' до свидания ' , ' прощай ' ]);

//Привязываем триггеры боту
$ bot -> addTrigger ( $ helloTrigger , $ bayTrigger );

//Отправляем ответ, если распознан $helloTrigger
$ bot ->sendResponse( $ helloTrigger , static function (){
    //$answer - экземпляр отправляемого ответа

    $ answer = new Response ();
    $ answer -> addText ( ' Привет! ' );
    $ answer -> addText ( ' Доброго времени суток! ' );

    //обязательно возвращаем объект Response
    return $ answer ;
);

//Отправляем ответ, если распознан $bayTrigger
$ bot ->sendResponse( $ bayTrigger , static function (){
    $ answer = new Response ();
    $ answer -> addText ( ' Прошай! ' );
    $ answer -> addText ( ' Всего доброго ' );

    //обязательно возвращаем объект Response
    return $ answer ;
);

Standard triggers

According to the protocol, the bot must have at least a trigger for greeting and error handling (call for help).

 //Будет вызван автоматически, при первом обращении пользователя к навыку
$ helloTrigger = new Trigger ( ' HELLO ' );
$ helloTrigger -> setAsInit ( true );

//Будет вызыван автоматически, если ну удалось распознать запрос
$ mistakeTrigger = new Trigger ( ' MISTAKE ' );
$ mistakeTrigger -> setAsMistake ( true );


//Отправляем ответ, если распознан $mistakeTrigger
$ bot -> sendResponse ( $ mistakeTrigger , static function (){
    $ answer = new Answer ();
    $ answer -> addText ( ' Не удалось понять вашу команду :( ' );
    return $ answer ;
);

If these triggers are not defined, the bot will send a default response with a link to this item. And if this is the reason why you are reading this text, the prank was a success.

Triggers

Trigger

Trigger is a command to which the bot must respond.

Tokens

Tokens – keywords, or query options (depending on the selected recognition type)

MORPHY_STRICT

This mode uses sequential comparison of groups of tokens, selecting only suitable options. The parsing proceeds from left to right - if the first group did not pass the search, the remaining groups will not be sorted through and the bot will begin viewing the next trigger. When all groups are entered for the first time, the trigger will be marked as recognized; otherwise they will not participate in the analysis

 $ greenTea -> linkTokens ([ ' дай ' , ' хочу ' , ' налей ' ],[ ' чай ' ],[ ' зеленый ' ]);
$ blackTea -> linkTokens ([ ' дай ' , ' хочу ' , ' налей ' ],[ ' чай ' ],[ ' черный ' , ' индийский ' ]);
$ coffeTrigger -> linkTokens ([ ' дай ' , ' хочу ' , ' налей ' ],[ ' кофе ' ]);

When requesting "Pour some black tea please" $blackTea will work; When requesting “I don’t have the strength to crave this invigorating coffee” – $coffeTrigger;

Pros:

• Well distinguishes between very similar queries
• When all token groups are matched for the first time, processing of subsequent triggers stops
• By adding triggers in order, you can determine those triggers that will be processed first. See point above.
• May cause an error trigger if the command was not recognized. In this example, having asked to pour beer, the bot will say that it does not have such powers.

Cons:

• It is necessary to strictly determine the importance of a particular keyword. In the case of $greenTea and $blackTea, with similar first two groups, the third group of tokens will play a decisive factor - black tea or green tea.
• Both the number of triggers and the number of token groups affect the speed of work.

Damerau-Loewenstein

Unlike MORPHY_STRICT, keywords will be determined automatically, but several query options must be specified. All triggers are included in the analysis; the trigger with the best match to the request will be selected for the recognized one.

 $ greenTea -> linkTokens ([ ' Налей зеленого чая ' ],[ ' Хочу зеленого чая ' ],[ ' Дай зеленый чай ' ]);
$ blackTeas -> linkTokens ([ ' Налей чергого чая ' ],[ ' Хочу черного чая ' ],[ ' Дай черный чай ' ]);
$ coffeTrigger -> linkTokens ([ ' Налей кофе ' ],[ ' Хочу кофе ' ],[ ' Дай кофе ' ]);

Pros:

• There is no need to define groups of keywords. It is enough to specify only a few possible options that the user may request
• Typically, the request is processed faster than a similar variation of MORPHY_STRICT

Cons:

• All triggers for which tokens are registered are processed. Even if the correct trigger was chosen first, the remaining triggers will still pass the test. The resulting trigger is the trigger with the highest match. Accordingly, the more triggers, the slower it works.
• Unlike MORPHY_STRICT, it cannot cause a recognition error message. This mode always produces some kind of trigger. In this example, having asked to pour beer, for some reason the bot pours coffee.

Delegation

In cases where the bot is used to execute commands sequentially, you can bind the next trigger to a trigger. For example, if you need to collect any information from the user, for example, first name, last name, etc.

 // Декларируем триггеры
$ nameTrigger = new Trigger ( ' NAME ' );
$ sNameTrigger = new Trigger ( ' SECOND_NAME ' );
$ yoTrigger = new Trigger ( ' YEARS ' );
$ personTrigger = new Trigger ( ' PERSON ' );

// Назначаем токены для триггера 
$ nameTrigger -> setTokens ([ ' давай ' , ' хочу ' , ' может ' ],[ ' знакомиться ' , ' познакомиться ' , ' представлюсь ' ]);

// Привязываем следующие триггеры
$ nameTrigger -> nextDelegate ( $ sNameTrigger );
$ sNameTrigger -> nextDelegate ( $ yoTrigger );
$ yoTrigger -> nextDelegate ( $ personTrigger );

// Обрабочтик запроса. Сработает если пользователь произнес "Давай познакомимся"
$ bot -> sendResponse ( $ nameTrigger , static function () use ( $ bot ){
    $ answer = new Response ();
    $ answer -> addText ( ' Какое твое имя? ' );
    return $ answer ;
});

// После шага $nameTrigger сработает обработчик $sNameTrigger
$ bot -> sendResponse ( $ sNameTrigger , static function () use ( $ bot ){
    $ answer = new Response ();
    $ answer -> addText ( ' А фамилия? ' );
    return $ answer ;
});

// После шага $sNameTrigger сработает обработчик $yoTrigger
$ bot -> sendResponse ( $ yoTrigger , static function () use ( $ bot ){
    $ answer = new Response ();
    $ answer -> addText ( ' Сколько тебе лет? ' );
    return $ answer ;
});

For each of the triggers you need to create a handler with a question. When the user requests “Well, let’s get acquainted,” the $nameTrigger trigger will fire. For the triggers $sNameTrigger and $yoTrigger, tokens are not needed (in general, in this case they will not be able to work, because the user will transmit information and the command cannot be recognized in it), they will be called automatically one after another.

Data

Triggers can be used not only as a way to determine a user command, but also to collect information.

 //$personTrigger – назначен как следующий триггер после $yoTrigger
$ bot -> sendResponse ( $ personTrigger , static function () use ( $ bot ){

    //В качестве аргумента строка, уникальное название триггера
    $ name = $ bot -> getTriggerData ( ' NAME ' );
    $ sName = $ bot -> getTriggerData ( ' SECOND_NAME ' );
    $ yo = $ bot -> getTriggerData ( ' YEARS ' );
    $ answer = new Answer ();
    $ answer -> addText ( " Хорошо { $ name } { $ sName } , я тебя запомнила, и что тебе { $ yo } лет – тоже " );
    return $ answer ;
);

The bot stores only one instance of data for a trigger, so only the last received data can be retrieved

Answers

Responses are the information that the bot sends to the user as soon as the trigger is triggered.

Text and TTS

 //$personTrigger – назначен как следующий триггер после $yoTrigger
$ bot -> sendResponse ( $ personTrigger , static function () use ( $ bot ){
    $ answer = new Answer ();
    $ answer -> addText ( ' Один вариант ответа ' , ' Од!ин вари!ант отв!ета ' );
    return $ answer ;
);

The addText method has two string arguments. The first is used to output text that will be displayed to the user, the second is the same text in TTS format.

Options

For greater interactivity, multiple possible answer options should be used. The shipping option will be selected randomly.

 $ bot -> sendResponse ( $ bullshitTrigger , static function () {
    $ answer = new Answer ();
    $ answer -> addText ( ' Да не может быть! ' );
    $ answer -> addText ( ' Чушь собачья! ' );
    $ answer -> addText ( ' Не верю! ' );
    return $ answer ;
);

Buttons

You can attach a button to respond. This could be a link to a web page or a button that, when clicked, will trigger a trigger. There can be several buttons and different types.

 $ bot -> sendResponse ( $ helloPerson , static function () {
    $ answer = new Answer ();
    $ answer -> addText ( ' Может познакомимся? ' );
    $ buttonY = new Button ( ' Давай ' );
    $ answer -> addButton ( $ button );
    $ buttonN = new Button ();
    $ buttonN -> setTitle ( ' Неа ' );
    return $ answer ;
);

In this example, when the button is clicked, $nameTrigger from the example in the “Delegation” section will be called. Thus $nameTrigger can be called either by the user's voice or by pressing a button if the user is not talkative.

Buttons

Types of buttons

The Alice bot can display buttons to users in two different forms - as a button placed under the dialog, and as a link inside the sent response.

 $ bButton = new Button ( ' Это кнопка ' );
//Будет отображена как кнопка, под диалогом. Со следующем ответом отображена не будет, если ее не привязатели к ответу Response
$ bButton -> setHide ( true );

$ bLink = new Button ( ' Это кнопка, но как ссылка ' )
//Будет отображена в ответе. Даже если пользователь выбирал что-то другие, эта ссылка так и останется в сообщении.
$ bButton-> setHide ( false );

Basic Features

 $ bButton = new Button ( ' Это кнопка ' );

* * * 

// Можно установить заголовок не в конструкторе, а в методе. Можно использовать как способ изменеия заголовка имеющейся кнопки, тем самым создавая вариативность
$ bButton -> setTitle ( ' Это все еще кнопка ' )

// К кнопке можно добавить ссылку. При клике на нее произойдет переход по адресу в браузере.
$ bButton -> addLink ( ' www.SITENAME.DOMAIN ' );

// Кнопке можно добавить обработчик какого-нибудь тригера. При клике на кнопку бот в первую очередь проверяет есть ли связанный Триггер для кнопки, и если есть – вызывает именно его.
$ bButton -> linkTrigger (Trigger $ trigger );

//Кнопке можно передать какие-нибудь данные, которые можно будет забрать и использовать, если пользователь нажимал на эту кнопку.
$ bButton -> addPayload ([ ' DATA ' => ' SOME_DATA ' ]);

Saving data

In addition to the data sent by the user, which is bound and saved by the trigger, you can also save your own data.

 $ bot ->sendResponse( $ firstRequest , static function () use ( $ bot ) {
    * * *
   $ bot -> storeCommonData ( ' Черный чай ' , ' TEA ' );
   $ bot -> getCommonData ( ' TEA ' ); // Вернет "Черный чай", в т.ч. если пользователь уже перешел к другому запросу
    * * *
);

 $ bot ->sendResponse( $ secondRequest , static function () use ( $ bot ) {
    * * *
   $ bot -> getCommonData ( ' TEA ' ); // Вернет "Черный чай", в т.ч. если пользователь уже перешел к другому запросу
    * * *
);

More options

Trigger reset

In cases where the trigger involves not only data acceptance, but also validation, looping should be used

 //Допустим что код триггера $chooseMeds – "MEDS"
$ bot -> sendResponse ( $ chooseMeds , static function () use ( $ bot ) {
    $ answer = new Response ();

    //Проверяем, это первичный запрос или цикл?
    if ( ! $ bot -> isRepeatedRequest ()) {
        //Нет, значит это первичный запрос со стороны пользователя, предлагаем выбор
        $ answer -> addText ( ' Какую таблетку ты выберешь, Нео? ' );
        //Задаем циклирование, результат будем проверять в этом же триггере
        $ bot -> setRepeat ( true );
    } else {
        //Неправильный выбор?
        if ( $ bot -> getTriggerData ( ' MEDS ' ) !== ' Синяя ' ) {
            $ answer -> addText ( ' Неверный выбор, Нео ' );
            //Задать цикл
            $ bot -> setRepeat ( true );
        } else {
            //Все ок, выход из триггера
            $ answer -> addText ( ' Ты сделал правильный выбор о-о ' );
        }
    }
    return $ answer ;
});

Internal delegation

Manual data substitution for a trigger

Post processing of response