avtonom / php-yandex-alisa
PHP lib for yandex alisa-bot dialogs
Requires
- php: ^5.5 || >=7.0
- greg0/lazer-database: ^1.1
- league/flysystem: ^1.0
- romaricdrigon/metayaml: ^1.1
This package is not auto-updated.
Last update: 2024-12-19 02:48:23 UTC
README
Библиотека для работы с Алисой.
- Вызов методов классов по запросу.
- Сохранение контекста диалога.
Пример блоковой системы находиться в папке blocks.
Содержание
- TODO
- Установка
- Описание констант
- Описание переменных
- Описание методов
- Система JSON-блоков
- Консоль Алиса
- index.php
- setting.yml
- Локальный Webhook.
TODO
Установка
composer require danil005/php-yandex-alisa
Описание констант
SKILL_NAME
Название навыка.
VERSION
Версия Алиса API. По умолчанию: 1.0
Описание переменных
private $startMessage = ""
Сообщение, которое будет отображаться при старте навыка.
private $startMessageTTS = ""
Сообщение, которое будет озвучено синтезом речи Yandex.
private $startButton = []
Кнопки, которые будут отображены при запуске навыка
private $version = self::VERSION
Наследует константу VERSION.
private $anyMessage = "Простите, я вас не понимаю."
Сообщение, которое будет отправлено пользователю в случае, если команда не будет найдена.
private $caseSensitive = true
Чувствительность к регистру сообщений.
private $speller = false
Проверка на орфографию.
public $vars = []
Переменная для обработки Prepare-функции.
private $request = []
Переменная, которая получает ответ от Алисы.
public $imagesDir = "images"
Директория с изображениями.
public $response = stdObject
Переменная для формирования ответа на полученный запрос от Алисы.
Описание методов
public setCaseSensitive(bool $sensitive = true): $this
Метод, который меняет чувствительность к регистру.
TRUE - включить чувствительность.
FALSE - выключить чувствительность.
public setImagesDir(String $path): $this
Устанавливает директорию с изображениями.
public setAny(String $message): $this
Метод, который устанавливает сообщение по умолчанию, если чат-бот не смог понять, что от него хотят.
public setVersion(String $version = self::VERSION): $this
Метод, который устанавливает версию Алиса API.
public setSpellerCorrect(bool $speller = false): $this
Исправление ошибок в тексте.
public setEndMessage(): $this
Метод, который завершает сессию и закрывает навык.
public addStartMessage(String $message): $this
Метод, который устанавливает сообщение при старте навыка.
public addStartTTS(String $message): $this
Метод, который устанавливает сообщение при старте навыка для синтеза речи.
public addStartButton(String $title, bool $hide = false, Array $payload = [], String $url = null): $this
Метод, который устанавливает кнопки при старте навыка.
public addButton(String $title, bool $hide = false, Array $payload = [], String $url = null): $this
Метод, который устанавливает кнопки.
ВНИМАНИЕ! Обязательно перед этим методом использовать sendMessage();
public sendMessage(String $message, String $tts = "", bool $speller = false ): $this
Отправить сообщение пользователю.
Использовать speller в этом методе не так важно, ведь вы сами можете вводить корректный текст, однако если вы не уверены в написании или боитесь, что где-то сделали опечатку, то можете использовать этот аргумент и поставить его на TRUE.
Также использование аргумента speller очень хорошо сочетается с методом prepare.
public sendImage(String $path, String $title = "", String $description = "", Array $options = []): $this
Метод, которые отобразить изображение. Если указать его, то sendMessage вызывать нет смысла. Внимание, чтобы отобразить изображение, вам необходимо его загрузить на сервер Yandex. Для этого создана консоль - alisa.
Дополнительные настройки:
|Аргумент|Тип| Описание
|:--:|--|--|--
|url|String|Web-ссылка.
|payload|Array|Payload-запрос.
public sendGallery(Array $images, String $headerText = "", String $footerText = "", Array $footerOpt = []): $this
Метод, которые отобразить галерею. Если указать его, то sendMessage вызывать нет смысла. Внимание, чтобы отобразить изображение, вам необходимо его загрузить на сервер Yandex. Для этого создана консоль - alisa.
Дополнительные настройки:
|Аргумент|Тип| Описание
|:--:|--|--|--
|url|String|Web-ссылка.
|payload|Array|Payload-запрос.
|message|String|Сообщение, которое будет отправлено при нажатии на кнопку.
protected optionsQuestions(Array $list, String $command): bool
Вариация реагирования на фразы для выполнения определенного дейсвтия указанного в cmd().
protected optionsAnswers(Array $list): mixed
Отправить вариационный ответ пользователю. Например, если вы не хотите отправлять пользователю одно и тоже сообщение, то можно использовать этот метод и расширить диапазон речи.
protected optionsCallback(Array $list, Array $callback): $this
Метод, который позволяет делать логическую операцию ИЛИ. В этом случае указывается набор
фраз, которые возможны при возврате payload (Callback). В случае если это слово будет найдено, то выдает TRUE. Также можно отправлять несколько Payload для одного действия и тем самым через эту функцию написать их оба.
public prepare(String $getMessage, String $command): bool
Метод, который позволяет делать подготовленные запросы и в последствии выводить их. Возвращает true или false, а также записывает результат функции в переменную $this->vars.
Пример:
if( $this->prepare("Купить {what} за {price}", $command) ) {
$this->sendMessage("Вы уверены, что хотите купить
{$this->vars['whats']} за {$this->vars['price']}₽?");
return true;
}
Как вы можете заметить, ключи переменной vars отображают подготовленные ключи из аргумента String $getMessage.
public listen(): bool|null
Начать прослушивать Webhook. Данный метод обязательно указывать в конце цепочки.
public cmd(String $command)
Метод в котором необходимо обрабатывать все данные.
Обязательно указывать return true; после каждого условия.
if( $command == "привет" ) {
$this->sendMessage("Приветик")->addButton("А что ты умеешь?");
return true;
}
//Или
if( $this->optionsQuestions(["привет", "здравствуйте"]) ) {
$this
->sendMessage($this->optionsAnswers(["Добрый день!", "Я рада вас видеть!"]))
->addButton("А что ты умеешь?");
return true;
}
//Или
if( $this->prepare("забронируй мне {what} на {time} в {when}", $command) ) {
$this->sendMessage
("Мы забронировали
{$this->vars['what']}
на {$this->vars['time']}
в {$this->vars['when']}"
);
return true;
}
return false;
public payload(Array $callback)
Метод в котором необходимо обрабатывать все данные пришедших с payload..
Обязательно указывать return true; после каждого условия.
if( array_key_exists('help', $callback) ) {
$this->sendMessage('Много чего! А ты?');
return true;
}
//Или
if( $this->optionsCallback(["help", "helpme"], $callback) ) {
$this->sendMessage('Много чего! А ты?');
return true;
}
return false;
Система JSON-блоков
Просто, удобно, быстро.
Чтобы активировать блоковую систему, укажите в index.php (или в другом файле) метод setBlocksActions(true).
Что это такое?
Система JSON-блоков построена таким образом, чтобы можно было использовать SDK не трогая навыки программирования. Вам достаточно прочитать эту документацию и делать уже сейчас свои навыки. Пока эта система находиться на Alpha-стадии.
Файлы обработки
Всего 2 файла обработки:
Если у вас стоит setCaseSensitive(false), то обязательно писать маленькими буквами, разрешает писать хаотично в send-теле.
Описание Action
Главный файл блоковой системы.
Простой пример:
Это маленький пример, который демонстрирует работу навыка уже с готовым json-блоком. Он ограничен действиями, однако может прост в понимании.
[
{
"question": "привет",
"send": {
"message": "Добрый день!",
"tts": "Д+обрый---д+ень!"
}
}
]
Пример с вариацией сообщений:
Иногда хочется, чтобы навык реагировал на несколько фраз, а также отвечал не одним предложением, а каким-нибудь разным.
[
{
"question": [
"привет", "добрый день", "здравствуйте"
],
"send": {
"message": ["Добрый день", "С новым годом!"],
"tts": ["Д+обрый---д+ень!", "С н+овым г+одом!"]
}
}
]
ВНИМАНИЕ Рекомендуем указывать вариацию ответов в одинаковом порядке с синтезом речи, дабы не было разногласия: текст - один, а слова речи -другие.
Пример с добавлением кнопки:
Кнопки необходимо добавлять внутри тела send, там и прописывать логику.
...
},
"buttons": {
"title": "button1",
"hide": false,
"payload": [],
"url": null
}
Кнопок можно добавить несколько, для этого просто сделайте buttons как массив:
...
},
"buttons": [
{
"title": "button1",
"hide": false,
"payload": [],
"url": null
},
{
"title": "button2",
"hide": false,
"payload": [],
"url": null
},
...
]
Пример с подготовленные запросы:
Подготовленные запросы - это сложная конструкция позволяющая вам создавать различные запросы, например: забронируй гостиницу на пятницу в 15:40. Запрос будет выглядеть таким образом:
забронировать {what} на {when} в {time}
Такая конструкция может быть за место question.
[
{
"prepare": "купить {what}",
"send": {
"message": "Вы купили {what}!"
"tts": "Вы куп+или {what}!"
},
...
}
]
Переменные можно указывать в send-теле для отображения того, что написал пользователь.
Группировка prepare и question:
Вы также можете группировать вместе подготовленные запросы и обычные. Непосредственно в обоих этих методах возможно использовать вариацию. Однако блоковая система станет сложнее:
[
{
"question": ["купить", "приобрести"],
"prepare": ["купить {what}", "приобрести {what}"],
"send": {
"message": "Покупаем..." ,
"tts": "Покупаем..."
...
}
]
Также можно разделить ответы и создать их опциональными:
[
{
"question": ["купить", "приобрести"],
"prepare": ["купить {what}", "приобрести {what}"],
"send": {
"message": {
"question": "Покупаем...",
"prepare": "Покупаем {what}..."
},
"tts": {
"question": "Покуп+аем...",
"prepare": "Покуп+аем {what}..."
}
...
}
]
С кнопками тоже самое, что и с сообщениями:
[
{
"question": ["купить", "приобрести"],
"prepare": ["купить {what}", "приобрести {what}"],
"send": {
"message": {
"question": "Покупаем...",
"prepare": "Покупаем {what}..."
},
"tts": {
"question": "Покуп+аем...",
"prepare": "Покуп+аем {what}..."
},
"buttons": {
"prepare": [
{
"title": "ButtonPrepare1",
"hide": false,
"payload": [],
"url": null
},
{
"title": "ButtonPrepare2",
"hide": false,
"payload": [],
"url": null
}
],
"question": {
"title": "ButtonQuestion1",
"hide": false,
"payload": [],
"url": null
}
}
}
]
Как видите, помимо того, что можно добавить кнопку под каждый ответ, так их можно создать несколько. Это очень удобно и делает в два счета, да куда быстрее чем писать код.
Пример кода с кнопками и payload:
Payload - это аналог Callback на других сервисах.
...,
"buttons": {
"title": "ButtonPrepare1",
"hide": false,
"payload": {
"function": "test",
"vars": [
{
"function": "test",
"vars": {}
}
]
},
"url": null
},
...
Аргументы из payload:
ВНИМАНИЕ Если указать несколько payload, то отправка кнопок или сообщений не будет, но вы можете таким образом обрабатывать различную информацию. Например, произвести оплату.
Пример сложного JSON-блока:
[
{
"question": ["купить", "приобрести"],
"prepare": ["купить {what}", "приобрести {what}"],
"send": {
"message": {
"question": [
"Производим покупку...",
"Покупаем...",
"Оплачиваем..."
],
"prepare": [
"Покупаем {what}...",
"Приобретаем {what}..."
]
},
"tts": {
"question": [
"Произв+одим пок+упку...",
"Покуп+аем...",
"Опл+ачиваем..."
],
"prepare": [
"Покуп+аем {what}...",
"Приобрет+аем {what}..."
]
},
"buttons": {
"prepare": [
{
"title": "ButtonPrepare1",
"hide": false,
"payload": [
{
"function": "test",
"vars": {
"admin": "yes",
"age": 23
}
}
],
"url": null
},
{
"title": "ButtonPrepare2",
"hide": false,
"payload": [],
"url": "https://example.ru/"
}
],
"question": {
"title": "ButtonQuestion1",
"hide": true,
"payload": [],
"url": "https://example.ru/"
}
}
},
"end_session": false
}
]
Глобальное описание всех переменных:
Описание Payload
Payload файл необходим для обработки запросов отправленных с кнопок:
Пример запроса:
{
{
"buy": {
"sendMessage": {
"message": [
"Вы хотите купить $^what|asd$. Вы уверены?",
"Вы приобритаете $what$. Вы уверены?"
],
"tts": [
"Вы хотите купить $what$. Вы уверены?",
"Вы приобритаете $what$. Вы уверены?"
]
},
"sendButtons": [
{
"title": "Да, уверен.",
"hide": false,
"payload": [
{
"function": "yes_buy",
"vars": {}
}
],
"url": null
}
]
}
}
Описание аргументов:
Форматирование текста:
- получить переменную из переменной vars. Например вы передали: Купить {what}. Значит в payload нужно указать
- если стоит такой знак, значит это слово будет исправлено в случае допущенной ошибки. Например: Исправить {what}. В переменной what = (здровстуйте). На выходи мы получим исправленное слово => здравствуйте.
- условия ИЛИ. Если переменная param1 будет пуста, то выведет param2 и наоборот.
Консоль Алиса
Консоль, которая на данный момент создана для загрузки изображения и просмотра уже загруженных.
php alisa upload:get
Возвращает все загруженные изображения.
Images List
===========
ID: 11
ImageName: f3ccdd27d2000e3f
ImageFile: 1.jpg
ImageID: 1030494/88a816aaacf55838ade8
===========
...
php alisa upload:file <file_name>
Загружает изображение из папку, которую вы установили методом setImageDir().
php alisa upload:url <url>
Загружает изображение с указной ссылки.
index.php
Файл для запуска чат-бота. Вы также можете изменить название файла, однако необходимо указывать то, что приведено к примеру ниже:
$main = new \yandex\alisa\Alisa();
$main->addStartMessage("Добро пожаловать")->setCaseSensitive(false)->listen();
setting.yml
Файл для настройки стандартных констант.
skill-name: АлиВиксед
skill-id: 354e2695-98b3-4951-be30-e7e2efff5868
skill-token: AQAAAAAW2RNZAAT7o0Uw9ECNE0WFgqvKcoGUppc
Локальный Webhook:
Чтобы запустить локальный webhook необходимо пройти на ngrko и создать аккаунт.
После скачать программу и кинуть ее в удобно для вас место.
Запустите командную строку и пропишете:
ngrok http port
Если это локальный сайт, то можете написать ngrok http example.ru:port
В случае, если вы используете OpenServer , то необходимо еще указать алису в настройках:
При успешном запуске, просто введите этот адрес в Webhook URL:
Version: 2.1 Danil Sidorenko © MIT 2018