Библиотека для работы с Алисой. Пример блоковой системы находиться в папке blocks.
- TODO
- Установка
- Описание констант
- Описание переменных
- Описание методов
- Система JSON-блоков
- Консоль Алиса
- index.php
- setting.yml
- Локальный Webhook.
Дата | Описание релиза | Состояние |
---|---|---|
5.08.2018 | Теперь можно делать вариации вопросов и ответов. | done |
5.08.2018 | Выполнять payload-функции (callback). | done |
5.08.2018 | Проверка на орфографию. | done |
6.08.2018 | Поддержка подготовленных запросов. | done |
8.08.2018 | Реализация созданий навыков при помощи JSON-блоков. | done |
11.08.2018 | Отправка сообщений с фотографиями. | done 80% |
--- | Оплата при помощи компании Unitpay. | in plan |
composer require danil005/php-yandex-alisa:dev-master
Название навыка.
Версия Алиса API. По умолчанию: 1.0
Сообщение, которое будет отображаться при старте навыка.
Сообщение, которое будет озвучено синтезом речи Yandex.
Кнопки, которые будут отображены при запуске навыка
Наследует константу VERSION.
Сообщение, которое будет отправлено пользователю в случае, если команда не будет найдена.
Чувствительность к регистру сообщений.
Проверка на орфографию.
Переменная для обработки Prepare-функции.
Переменная, которая получает ответ от Алисы.
Директория с изображениями.
Переменная для формирования ответа на полученный запрос от Алисы.
Метод, который меняет чувствительность к регистру.
TRUE
- включить чувствительность.
FALSE
- выключить чувствительность.
Аргумент | Тип | Описание | По умолчанию |
---|---|---|---|
sensitive | bool | Чувствительно к регистру. | true |
Устанавливает директорию с изображениями.
Аргумент | Тип | Описание | По умолчанию |
---|---|---|---|
path | String | Директория с изображениями. | Обязательно |
Метод, который устанавливает сообщение по умолчанию, если чат-бот не смог понять, что от него хотят.
Аргумент | Тип | Описание | По умолчанию |
---|---|---|---|
message | String | Текст сообщения. | Обязательно |
Метод, который устанавливает версию Алиса API.
Аргумент | Тип | Описание | По умолчанию |
---|---|---|---|
version | String | Версия Алиса API. | Данные с константы VERSION |
Исправление ошибок в тексте.
Аргумент | Тип | Описание | По умолчанию |
---|---|---|---|
speller | bool | Установить проверку на орфографию и ее исправления в случае нахождении ошибки. | false |
Метод, который завершает сессию и закрывает навык.
Метод, который устанавливает сообщение при старте навыка.
Аргумент | Тип | Описание | По умолчанию |
---|---|---|---|
message | String | Текст сообщения. | Обязательно |
Метод, который устанавливает сообщение при старте навыка для синтеза речи.
Аргумент | Тип | Описание | По умолчанию |
---|---|---|---|
message | String | Текст сообщения. | Обязательно |
public addStartButton(String $title, bool $hide = false, Array $payload = [], String $url = null): $this
Метод, который устанавливает кнопки при старте навыка.
Аргумент | Тип | Описание | По умолчанию |
---|---|---|---|
title | String | Название кнопки. | Обязательно |
hide | bool | Спрятать кнопки после нажатия. | false |
payload | Array | Отправить дополнительные данные для обработки. | [] |
url | String | URL-ссылка | null |
Метод, который устанавливает кнопки.
ВНИМАНИЕ! Обязательно перед этим методом использовать sendMessage();
Аргумент | Тип | Описание | По умолчанию |
---|---|---|---|
title | String | Название кнопки. | Обязательно |
hide | bool | Спрятать кнопки после нажатия. | false |
payload | Array | Отправить дополнительные данные для обработки. | [] |
url | String | URL-ссылка | null |
Отправить сообщение пользователю.
Использовать speller в этом методе не так важно, ведь вы сами можете вводить корректный текст, однако если вы не уверены в написании или боитесь, что где-то сделали опечатку, то можете использовать этот аргумент и поставить его на TRUE
.
Также использование аргумента speller очень хорошо сочетается с методом prepare.
Аргумент | Тип | Описание | По умолчанию |
---|---|---|---|
message | String | Текст сообщения. | Обязательно |
tts | String | Синтез речи, ударения, паузы. | "" |
speller | bool | Проверка на орфографию и исправление, если будет найдена ошибка. | false |
public sendImage(String $path, String $title = "", String $description = "", Array $options = []): $this
Метод, которые отобразить изображение. Если указать его, то sendMessage вызывать нет смысла. Внимание, чтобы отобразить изображение, вам необходимо его загрузить на сервер Yandex. Для этого создана консоль - alisa.
Аргумент | Тип | Описание | По умолчанию |
---|---|---|---|
path | String | Название файла. | Обязательно |
title | String | Подпись под фотографией | "" |
description | String | Описание под фотографией | "" |
options | Array | Дополнительные настройки | [] |
|Аргумент|Тип| Описание
|:--:|--|--|--
|url|String|Web-ссылка.
|payload|Array|Payload-запрос.
public sendGallery(Array $images, String $headerText = "", String $footerText = "", Array $footerOpt = []): $this
Метод, которые отобразить галерею. Если указать его, то sendMessage вызывать нет смысла. Внимание, чтобы отобразить изображение, вам необходимо его загрузить на сервер Yandex. Для этого создана консоль - alisa.
Аргумент | Тип | Описание | По умолчанию |
---|---|---|---|
images | Array | Массив с изображениями. | Обязательно |
headerText | String | Заголовок галереи. | "" |
footerText | String | Текст под изображениями. | "" |
footerOpt | Array | Дополнительные настройки | [] |
|Аргумент|Тип| Описание
|:--:|--|--|--
|url|String|Web-ссылка.
|payload|Array|Payload-запрос.
|message|String|Сообщение, которое будет отправлено при нажатии на кнопку.
Вариация реагирования на фразы для выполнения определенного дейсвтия указанного в cmd().
Аргумент | Тип | Описание | По умолчанию |
---|---|---|---|
list | Array | Лист ключевых слов для вызова действия. | Обязательно |
command | String | Команда пришедшая от пользователя на сервер. | Обязательно |
Отправить вариационный ответ пользователю. Например, если вы не хотите отправлять пользователю одно и тоже сообщение, то можно использовать этот метод и расширить диапазон речи.
Аргумент | Тип | Описание | По умолчанию |
---|---|---|---|
list | array | Лист фраз, которые будет выдавать Алиса-навык. | Обязательно |
Метод, который позволяет делать логическую операцию ИЛИ. В этом случае указывается набор
фраз, которые возможны при возврате payload (Callback). В случае если это слово будет найдено, то выдает TRUE
. Также можно отправлять несколько Payload для одного действия и тем самым через эту функцию написать их оба.
Аргумент | Тип | Описание | По умолчанию |
---|---|---|---|
list | Array | Лист ключевых слов. | Обязательно |
callback | String | Обязательная переменная, которая передается в функцию для обработки. | Обязательно |
Метод, который позволяет делать подготовленные запросы и в последствии выводить их. Возвращает true
или false
, а также записывает результат функции в переменную $this->vars
.
Пример:
if( $this->prepare("Купить {what} за {price}", $command) ) {
$this->sendMessage("Вы уверены, что хотите купить
{$this->vars['whats']} за {$this->vars['price']}₽?");
return true;
}
Как вы можете заметить, ключи переменной vars отображают подготовленные ключи из аргумента String $getMessage
.
Аргумент | Тип | Описание | По умолчанию |
---|---|---|---|
getMessage | String | Сообщение, которое должен принять навык для обработки данных. | Обязательно |
command | String | Сообщение которое придет от пользователя. | Обязательно |
Начать прослушивать Webhook. Данный метод обязательно указывать в конце цепочки.
Метод в котором необходимо обрабатывать все данные.
Обязательно указывать 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;
Метод в котором необходимо обрабатывать все данные пришедших с 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;
Просто, удобно, быстро.
Чтобы активировать блоковую систему, укажите в index.php (или в другом файле) метод setBlocksActions(true)
.
Система JSON-блоков построена таким образом, чтобы можно было использовать SDK не трогая навыки программирования. Вам достаточно прочитать эту документацию и делать уже сейчас свои навыки. Пока эта система находиться на Alpha-стадии.
Всего 2 файла обработки:
Файл | Описание | Местонахождение |
---|---|---|
action.json | Главный файл, который берет на себя ответственность выполнять определенны действия. | \dir_project\blocks\action.json |
payload.json | Файл для обработки payload запросов (callback). | \dir_project\blocks\payload. |
Если у вас стоит setCaseSensitive(false)
, то обязательно писать маленькими буквами, разрешает писать хаотично в send-теле.
Главный файл блоковой системы.
Это маленький пример, который демонстрирует работу навыка уже с готовым json-блоком. Он ограничен действиями, однако может прост в понимании.
[
{
"question": "привет",
"send": {
"message": "Добрый день!",
"tts": "Д+обрый---д+ень!"
}
}
]
Аргумент | Тип данных | Описание |
---|---|---|
question | String | Сообщение, которое будет писать пользователь. |
send | Array | Ответить на сообщение навыку. |
message | String | Сообщение, которое будет отправлено в ответ. |
tts | String | Синтез речи. |
Иногда хочется, чтобы навык реагировал на несколько фраз, а также отвечал не одним предложением, а каким-нибудь разным.
[
{
"question": [
"привет", "добрый день", "здравствуйте"
],
"send": {
"message": ["Добрый день", "С новым годом!"],
"tts": ["Д+обрый---д+ень!", "С н+овым г+одом!"]
}
}
]
Аргумент | Тип данных | Описание |
---|---|---|
question | Array | Сообщение, которое будет писать пользователь. |
send | Array | Ответить на сообщение навыку. |
message | Array | Сообщение, которое будет отправлено в ответ. |
tts | Array | Синтез речи. |
ВНИМАНИЕ Рекомендуем указывать вариацию ответов в одинаковом порядке с синтезом речи, дабы не было разногласия: текст - один, а слова речи -другие.
Кнопки необходимо добавлять внутри тела send, там и прописывать логику.
...
},
"buttons": {
"title": "button1",
"hide": false,
"payload": [],
"url": null
}
Аргумент | Тип данных | Описание |
---|---|---|
buttons | Array | Объявление кнопок в теле send. |
title | String | Название кнопки. |
hide | Bool | Спрятать кнопку после нажатия. |
payload | Array | Аналог callback, отправляет данные на сервер. Дальше будет расписано, как можно будет это использовать. |
url | String | Кнопка с ссылкой. |
Кнопок можно добавить несколько, для этого просто сделайте 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}!"
},
...
}
]
Аргумент | Тип данных | Описание |
---|---|---|
prepare | String | Подготовленный запрос. Переменная указывается в фигурных скобках. Она может быть любой, но должна начинаться с буквы. |
Переменные можно указывать в send-теле для отображения того, что написал пользователь.
Вы также можете группировать вместе подготовленные запросы и обычные. Непосредственно в обоих этих методах возможно использовать вариацию. Однако блоковая система станет сложнее:
[
{
"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 - это аналог Callback на других сервисах.
...,
"buttons": {
"title": "ButtonPrepare1",
"hide": false,
"payload": {
"function": "test",
"vars": [
{
"function": "test",
"vars": {}
}
]
},
"url": null
},
...
Аргументы из payload:
Аргумент | Тип данных | Описание |
---|---|---|
function | String | Функция, которая указана в payload.json. Настройка действия делается в этом файле. |
vars | Array | Дополнительные переменные, которые будут переданы. Если вы использовали подготовленные запросы, то все переменные будут переданы во все vars кнопок, которые будут созданы. |
ВНИМАНИЕ Если указать несколько payload, то отправка кнопок или сообщений не будет, но вы можете таким образом обрабатывать различную информацию. Например, произвести оплату.
[
{
"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
}
]
Глобальное описание всех переменных:
Аргумент | Тип данных | Описание |
---|---|---|
question | String|Array | Принимает сообщения для обработки. Если использовать массив, то будет вариация того, что может написать пользователь. |
prepare | String|Array | Подготовленные запросы, которые можно использовать за место question. Если использовать массив, то будет вариация того, что может написать пользователь. |
send | Array | Массив, который обрабатывает все действия. |
message | String|Array | Аргумент, который отправляет сообщение пользователю. Если это массив, то будет создана вариация ответов. Рекомендуется делать соответствие текстов с TTS, чтобы не было асинхронности речевого синтеза и текста. Также можно указать тип ответа и на какой аргумент prepare или question. |
tts | String|Array | Аргумент, который создает синтез речи для текста. Если это массив, то будет создана вариация ответов. Рекомендуется делать соответствие текстов с TTS, чтобы не было асинхронности речевого синтеза и текста. |
buttons | Array | Создание кнопок. Можно указать тип ответа prepare или question, добавить несколько кнопок. |
title | String | Название кнопки. |
hide | Bool | Скрыть кнопку после нажатия. |
payload | Array | Отправить payload-запрос. |
function | String | Название функции в файле payload.json. |
vars | Array | Переменные для передачи с payload-запросом. |
url | String | Отправить по ссылки при нажатии на кнопку. |
end_session | Bool | Завершить сессию. |
Payload файл необходим для обработки запросов отправленных с кнопок:
{
{
"buy": {
"sendMessage": {
"message": [
"Вы хотите купить $^what|asd$. Вы уверены?",
"Вы приобритаете $what$. Вы уверены?"
],
"tts": [
"Вы хотите купить $what$. Вы уверены?",
"Вы приобритаете $what$. Вы уверены?"
]
},
"sendButtons": [
{
"title": "Да, уверен.",
"hide": false,
"payload": [
{
"function": "yes_buy",
"vars": {}
}
],
"url": null
}
]
}
}
Описание аргументов:
Аргумент | Тип данных | Описание |
---|---|---|
buy | String | Название функции, за место buy можно использовать любые другие слова. Это название нужно передавать в button => payload => function. |
sendMessage | Array | Аргумент для отправки сообщения. |
message | String|Array | Отправить сообщение. Если это массив, то будет создана вариация сообщений. Рекомендуется делать соответствие текстов с TTS, чтобы не было асинхронности речевого синтеза и текста. |
tts | String|Array | Отправить синтез речи. Если это массив, то будет создана вариация сообщений. Рекомендуется делать соответствие текстов с TTS, чтобы не было асинхронности речевого синтеза и текста. |
sendButton | Array | Отправляет кнопки. |
title | String | Название кнопки. |
hide | Bool | Скрыть кнопку после нажатия. |
payload | Array | Выполнить Payload-запрос. |
function | String | Название функции в payload.json. |
vars | Array | Переменные для передачи с payload-запросом. |
url | String | Отправить по ссылки при нажатии на кнопку. |
$param$ - получить переменную из переменной vars. Например вы передали: Купить {what}. Значит в payload нужно указать$what$
$^param$ - если стоит такой знак, значит это слово будет исправлено в случае допущенной ошибки. Например: Исправить {what}. В переменной what = (здровстуйте). На выходи мы получим исправленное слово => здравствуйте.
$param1|param2$ - условия ИЛИ. Если переменная param1 будет пуста, то выведет param2 и наоборот.
Консоль, которая на данный момент создана для загрузки изображения и просмотра уже загруженных.
Возвращает все загруженные изображения.
Images List
===========
ID: 11
ImageName: f3ccdd27d2000e3f
ImageFile: 1.jpg
ImageID: 1030494/88a816aaacf55838ade8
===========
...
Загружает изображение из папку, которую вы установили методом setImageDir()
.
Загружает изображение с указной ссылки.
Файл для запуска чат-бота. Вы также можете изменить название файла, однако необходимо указывать то, что приведено к примеру ниже:
$main = new \yandex\alisa\Alisa();
$main->addStartMessage("Добро пожаловать")->setCaseSensitive(false)->listen();
Файл для настройки стандартных констант.
skill-name: АлиВиксед
skill-id: 354e2695-98b3-4951-be30-e7e2efff5868
skill-token: AQAAAAAW2RNZAAT7o0Uw9ECNE0WFgqvKcoGUppc
Константа | Описание |
---|---|
skill-name | Название навыка. |
skill-id | ID-навыка. |
skill-token | OAuth-токен Dialogs для работы с изображениями. |
Чтобы запустить локальный webhook необходимо пройти на ngrko и создать аккаунт.
После скачать программу и кинуть ее в удобно для вас место.
Запустите командную строку и пропишете:
ngrok http port
Если это локальный сайт, то можете написать ngrok http example.ru:port
В случае, если вы используете OpenServer , то необходимо еще указать алису в настройках:
При успешном запуске, просто введите этот адрес в Webhook URL:
Version: 2.1 Danil Sidorenko © MIT 2018