README

Библиотека для работы с Алисой. Пример блоковой системы находиться в папке blocks.

Содержание

1. TODO
2. Установка
3. Описание констант
4. Описание переменных
5. Описание методов
6. Система JSON-блоков
   • Что это такое?
   • Файлы обработки
   • Описание Action
     • Простой пример
     • Пример с вариацией сообщений
     • Пример с добавлением кнопки
     • Пример с подготовленные запросы
     • Группировка prepare и question
     • Пример кода с кнопками и payload
     • Пример сложного JSON-блока
   • Описание Payload
     • Пример запроса
     • Форматирование текста
7. Консоль Алиса
   • Получить загруженные файлы
   • Загрузить с сервера
   • Загрузить с сайта
8. index.php
9. setting.yml
10. Локальный Webhook.

TODO

Установка

composer require danil005/php-yandex-alisa:dev-master

Описание констант

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  
			  }  
		 ]
	}
}

Описание аргументов:

Форматирование текста:

$param$ - получить переменную из переменной vars. Например вы передали: Купить {what}. Значит в payload нужно указать $what$

$^param$ - если стоит такой знак, значит это слово будет исправлено в случае допущенной ошибки. Например: Исправить {what}. В переменной what = (здровстуйте). На выходи мы получим исправленное слово => здравствуйте.

$param1|param2$ - условия ИЛИ. Если переменная 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