Виды кнопок в Яндекс.Алиса? Как они выглядят и как использовать?

Однажды я увидел красивое меню в одном из навыков для Алисы, и решил сделать такое же. Потратил на это почти день, чтобы разобраться какими могут быть кнопки и какие у них свойства. После нескольких недель я почти забыл все нюансы поведения разных кнопок в диалогах.

Поэтому решил записать все варианты как можно оформить кнопки в диалоге, так как документация для диалогов алисы не содержит большого количество примеров. А также, чтобы самому можно было вернуться и посмотреть. Надеюсь что кому-то это будет тоже полезно.

Чтобы меньше путаться, я буду называть кнопки c параметром hide: True - подсказками (suggests).

1. Обычная кнопка с параметрами url и payload

При нажатии открывается ссылка указанная в параметрах кнопки.

Вот как должен выглядит ответ в json:

{
    "response": {
        "text": "Example text for button with url and payload.",
        "buttons": [
            {
                "title": "Button with url and payload.",
                "payload": "button1",
                "url": "https://www.maxim-m.ru/",
                "hide": false
            }
        ],
        "end_session": false
    },
    "session": {
        "session_id": "<session_id>",
        "message_id": 1,
        "user_id": "<user_id>"
    },
    "version": "1.0"
}

При нажатии кнопки диалог останавливается и отравляет в навык следующий запрос:

{
    "meta": {
        "locale": "ru-RU",
        "timezone": "Europe/Moscow",
        "client_id": "YaBro/19.10.3.281 ( ; Windows 10.0.18363)",
        "interfaces": {
            "screen": {}
        }
    },
    "request": {
        "command": "",
        "original_utterance": "",
        "type": "ButtonPressed",
        "payload": "button1"
    },
    "session": {
        "new": false,
        "message_id": 4,
        "session_id": "<session_id>",
        "skill_id": "<skill_id>",
        "user_id": "<user_id>"
    },
    "version": "1.0"
}

Можно использовать данный запрос для сбора метрики что пользователь нажал кнопку и открыл сайт.

Однако во время написания статьи обнаружился баг - запрос от кнопки с payload и url приходил только от Алисы из Яндекс Браузера. Из мобильных клиентов запросы не приходили по нажатиям на подобные кнопки.

2. Подсказка с параметрами url и payload

При нажатии открывается ссылка указанная в параметрах кнопки.

Вот ответ в json:

{
    "response": {
        "text": "Example text for suggest with url and payload.",
        "buttons": [
            {
                "title": "Suggest with url and payload.",
                "payload": "button1",
                "url": "https://www.maxim-m.ru/",
                "hide": true
            }
        ],
        "end_session": false
    },
    "session": {
        "session_id": "<session_id>",
        "message_id": 1,
        "user_id": "<user_id>"
    },
    "version": "1.0"
}

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

3. Кнопка с параметром url

Визуально ничем не отличается от кнопки с url и payload

По нажатию кнопка просто открывает ссылку и ничего не отправляет в навык. Вот так выглядит json для кнопки:

{
    "response": {
        "text": "Example text for button with url.",
        "buttons": [
            {
                "title": "Button with url.",
                "url": "https://www.maxim-m.ru/",
                "hide": false
            }
        ],
        "end_session": false
    },
    "session": {
        "session_id": "<session_id>",
        "message_id": 1,
        "user_id": "<user_id>"
    },
    "version": "1.0"
}

4. Подсказка с параметром url

При нажатии открывается ссылка указанная в параметрах кнопки.

Подсказка с ссылкой тоже не отправляет ничего в навык.

Вот так выглядит json:

{
    "response": {
        "text": "Example text for suggest with url.",
        "buttons": [
            {
                "title": "Suggest with url.",
                "url": "https://www.maxim-m.ru/",
                "hide": false
            }
        ],
        "end_session": false
    },
    "session": {
        "session_id": "<session_id>",
        "message_id": 1,
        "user_id": "<user_id>"
    },
    "version": "1.0"
}

5. Кнопка с параметром payload

При нажатии параметр payload должен отправить в навык.

Вот json для отображения кнопки:

{
    "response": {
        "text": "Example text for button with payload.",
        "buttons": [
            {
                "title": "Button with payload.",
                "payload": "button5",
                "hide": false
            }
        ],
        "end_session": false
    },
    "session": {
        "session_id": "<session_id>",
        "message_id": 1,
        "user_id": "<user_id>"
    },
    "version": "1.0"
}

Здесь уже запрос ButtonPressed приходит со всех устройств:

{
    "meta": {
        "locale": "ru-RU",
        "timezone": "Europe/Moscow",
        "client_id": "YaBro/19.10.3.281 ( ; Windows 10.0.18363)",
        "interfaces": {
            "screen": {}
        }
    },
    "request": {
        "command": "",
        "original_utterance": "",
        "type": "ButtonPressed",
        "payload": "button5"
    },
    "session": {
        "new": false,
        "message_id": 4,
        "session_id": "<session_id>",
        "skill_id": "<skill_id>",
        "user_id": "<user_id>"
    },
    "version": "1.0"
}

6. Подсказка с параметром payload

При нажатии параметр payload должен отправить в навык.

json:

{
    "response": {
        "text": "Example text for suggest with payload.",
        "buttons": [
            {
                "title": "Suggest with payload.",
                "payload": "button6",
                "hide": true
            }
        ],
        "end_session": false
    },
    "session": {
        "session_id": "<session_id>",
        "message_id": 1,
        "user_id": "<user_id>"
    },
    "version": "1.0"
}

Так же как для предыдущей кнопки, payload приходит со всех устройств:

{
    "meta": {
        "locale": "ru-RU",
        "timezone": "Europe/Moscow",
        "client_id": "YaBro/19.10.3.281 ( ; Windows 10.0.18363)",
        "interfaces": {
            "screen": {}
        }
    },
    "request": {
        "command": "",
        "original_utterance": "",
        "type": "ButtonPressed",
        "payload": "button6"
    },
    "session": {
        "new": false,
        "message_id": 4,
        "session_id": "<session_id>",
        "skill_id": "<skill_id>",
        "user_id": "<user_id>"
    },
    "version": "1.0"
}

7. Галерея картинок - кнопкам

Список изображений - кнопок.

В данном случае у всех кнопок есть параметр url и payload. И их поведение аналогично кнопкам из пунктов 1 и 2.

А вот и json:

{
    "response": {
        "text": "Example reply for skill",
        "tts": "Example reply for skill",
        "card": {
            "type": "ItemsList",
            "header": {
                "text": "Header for List of images",
            },
            "items": [
                {
                    "image_id": "<image_id>",
                    "title": "Title",
                    "description": "Description",
                    "button": {
                        "text": "Image button",
                        "url": "https://www.maxim-m.ru/",
                        "payload": "button7_1"
                    }
                },
                {
                    "image_id": "<image_id>",
                    "title": "Title",
                    "description": "Description",
                    "button": {
                        "text": "Image button",
                        "url": "https://www.maxim-m.ru/",
                        "payload": "button7_2"
                    }
                }
            ],
            "footer": {
                "text": "Text in footer",
                "button": {
                    "text": "Button in footer",
                    "url": "https://www.maxim-m.ru/",
                    "payload": "footer"
                }
            }
        },
        "end_session": false
    },
    "session": {
        "session_id": "<session_id>",
        "message_id": 1,
        "user_id": "<user_id>"
    },
    "version": "1.0"
}

При этом вы можете добавить подсказки. Однако обычные кнопки добавить не получится, придется довольствоваться одной кнопкой в footer.

Также не забывайте что footer и header не обязательно указывать.

8. Галерея картинок с кнопками и подсказками

Подсказка под списком картинок

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

Вот json:

{
    "response": {
        "text": "Example reply for skill",
        "tts": "Example reply for skill",
        "card": {
            "type": "ItemsList",
            "header": {
                "text": "Header for List of images",
            },
            "items": [
                {
                    "image_id": "<image_id>",
                    "title": "Title",
                    "description": "Описание",
                    "button": {
                        "text": "Image button",
                        "payload": "button8_1"
                    }
                },
                {
                    "image_id": "<image_id>",
                    "title": "Title",
                    "description": "Description",
                    "button": {
                        "text": "Image button",
                        "payload": "button8_2"
                    }
                }
            ],
            "footer": {
                "text": "Text in footer",
                "button": {
                    "text": "Button in footer",
                    "url": "https://www.maxim-m.ru/",
                    "payload": "footer"
                }
            }
        },
        "buttons": [
            {
                "title": "Suggest with url and payload",
                "payload": "payload",
                "url": "https://www.maxim-m.ru/",
                "hide": true
            }
        ],
        "end_session": false
    },
    "session": {
        "session_id": "<session_id>",
        "message_id": 1,
        "user_id": "<user_id>"
    },
    "version": "1.0"
}

9. Карточка - кнопка и подсказка

Подсказка под карточкой с изображением.

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

Поведение кнопок соответствует кнопка в предыдущих примерах и зависит от наличия/отсутствия параметров payload или url.

json:

{
    "response": {
        "text": "Example reply for skill",
        "tts": "Example reply for skill",
        "card": {
            "type": "BigImage",
            "image_id": "<image_id>",
            "title": "Title",
            "description": "Deccription",
            "button": {
                "text": "Image button",
                "url": "https://www.maxim-m.ru/",
                "payload": "button9"
            }
        },
        "buttons": [
            {
                "title": "Suggest with url and payload",
                "payload": "suggest_payload",
                "url": "https://www.maxim-m.ru/",
                "hide": true
            }
        ],
        "end_session": false
    },
    "session": {
        "session_id": "<session_id>",
        "message_id": 1,
        "user_id": "<user_id>"
    },
    "version": "1.0"
}

Думаю, пока что, этого хватит. Пишите если надо добавить другие примеры, или, например рассказать про другие нюансы разработки навыков для Алисы.

Источник: KubeApps